Migrating from RapiDoc v10 to v11

RapiDoc v11 introduces a modernized styling architecture designed around W3C web standards, CSS custom properties (design tokens), and CSS Shadow Parts (::part()).

This major release eliminates attribute bloat by deprecating granular styling attributes (bg-color, text-color, nav-bg-color, primary-color, regular-font, etc.) in favor of standard CSS declarations and high-level design tokens.

Why the Styling Architecture Changed

In RapiDoc v10, customizing visuals required configuring dozens of specialized HTML attributes. While functional, this approach:

• Cluttered HTML templates with styling configuration.
• Failed to integrate cleanly with modern design systems (Tailwind CSS, shadcn/ui, CSS variables).
• Lacked native CSS cascade and media query support (such as automatic prefers-color-scheme detection).
• Could not leverage rich CSS capabilities like gradients, backdrop blur, transitions, and hover states.

RapiDoc v11 standardizes styling into high-level declarative tokens on the element itself, and CSS variables & ::part() pseudo-elements for all visual customizations.

---

1. Quick Summary of Breaking Changes

Here is an overview of what changed between v10 and v11:

1. theme attribute redefined:
   • v10: Used for base mode (theme="dark" or theme="light").
   • v11: Sets the color palette preset (amber, blue, emerald, violet, graphite, rose, slate) OR accepts any custom brand hex code (theme="#2563eb").
2. color-scheme attribute introduced:
   • Controls light/dark surface rendering: color-scheme="dark", color-scheme="light", or color-scheme="system".
3. Granular color attributes deprecated:
   • bg-color, text-color, header-color, primary-color are replaced by the theme preset engine, --background, --foreground, --primary, or ::part().
4. Navigation color attributes deprecated:
   • nav-bg-color, nav-text-color, nav-hover-bg-color, nav-hover-text-color, nav-accent-color, nav-accent-text-color are replaced by CSS custom properties and rapi-doc::part(section-navbar).
5. Font attributes deprecated:
   • regular-font and mono-font are replaced by standard CSS variables --font-sans and --font-mono.
   • font-size="default | large | largest" is replaced by proportional UI scaling attribute scale="sm | default | lg".

---

2. Deprecated Attributes & Modern Replacements

The table below maps every deprecated v10 attribute to its modern v11 replacement:

Legacy v10 Attribute	Status	Modern v11 Replacement	Type / Mechanism
theme="light" / theme="dark"	Deprecated	color-scheme	HTML Attribute
primary-color	Deprecated	theme or --primary	HTML Attribute / CSS Variable
bg-color	Deprecated	--background or color-scheme	CSS Variable / HTML Attribute
text-color	Deprecated	--foreground	CSS Variable
header-color	Deprecated	::part(section-header) or --header-bg	CSS Shadow Part / Variable
regular-font	Deprecated	--font-sans (or --font-regular)	CSS Variable
mono-font	Deprecated	--font-mono	CSS Variable
font-size	Deprecated	scale	HTML Attribute
nav-bg-color	Deprecated	::part(section-navbar) or --nav-background	CSS Shadow Part / Variable
nav-text-color	Deprecated	--nav-foreground or ::part(section-navbar)	CSS Variable / Shadow Part
nav-hover-bg-color	Deprecated	--nav-hover-bg or ::part(nav-item):hover	CSS Variable / Shadow Part
nav-hover-text-color	Deprecated	--nav-hover-fg or ::part(nav-item):hover	CSS Variable / Shadow Part
nav-accent-color	Deprecated	theme or --primary	HTML Attribute / CSS Variable
nav-accent-text-color	Deprecated	--nav-accent-fg (or --primary-foreground in colored-block)	CSS Variable

---

3. Migration Details by Feature Area

3.1 Theme & Color Scheme Modernization

In v10, you configured dark mode and primary button colors using separate attributes:

v10 (Legacy)

<!-- v10: theme set the surface, primary-color set the accent -->
<rapi-doc
  spec-url="https://api.example.com/openapi.json"
  theme="dark"
  primary-color="#3b82f6"
  bg-color="#0f172a"
  text-color="#f8fafc"
></rapi-doc>

v11 (Modern)

<!-- v11: color-scheme sets surface, theme sets preset or hex -->
<rapi-doc
  spec-url="https://api.example.com/openapi.json"
  color-scheme="dark"
  theme="#3b82f6"
></rapi-doc>

Automatic Contrast Calculation in v11

When you set theme="#3b82f6" (or any hex code), RapiDoc v11 automatically evaluates the luminance of your brand color. If the color is light, it renders high-contrast black text on buttons and badges; if dark, it renders white text. You no longer need to manually tune text contrast for primary buttons!

---

3.2 Replacing Color Attributes with CSS Custom Properties

Instead of configuring colors directly on HTML attributes, assign standard CSS custom properties on <rapi-doc> in your stylesheet or <style> block.

v10 (Legacy Attributes)

<rapi-doc
  spec-url="https://api.example.com/openapi.json"
  bg-color="#0b1120"
  text-color="#e2e8f0"
  primary-color="#10b981"
></rapi-doc>

v11 (CSS Variables)

<style>
  rapi-doc {
    /* Surface and Text tokens */
    --background: #0b1120;
    --foreground: #e2e8f0;

    /* Primary Accent token */
    --primary: #10b981;
    --primary-foreground: #ffffff;

    /* Border token */
    --border: #1e293b;

}

</style>

<rapi-doc
spec-url="https://api.example.com/openapi.json"
color-scheme="dark"

> </rapi-doc>

---

3.3 Replacing Navigation Attributes with CSS Variables & Shadow Parts

In v10, sidebar styling required up to six distinct attributes. In v11, you can style the sidebar using clean CSS custom properties or standard ::part(section-navbar) selectors.

v10 (Legacy Attributes)

<rapi-doc
  spec-url="https://api.example.com/openapi.json"
  nav-bg-color="#0f172a"
  nav-text-color="#94a3b8"
  nav-hover-bg-color="#1e293b"
  nav-hover-text-color="#ffffff"
  nav-accent-color="#3b82f6"
  nav-accent-text-color="#ffffff"
></rapi-doc>

v11 (CSS Variables)

/* Style sidebar navigation with design tokens */
rapi-doc {
  --nav-background: #0f172a;
  --nav-foreground: #94a3b8;
  --nav-hover-bg: #1e293b;
  --nav-hover-fg: #ffffff;
  --nav-accent-fg: #3b82f6;
}

v11 (CSS Shadow Parts)

/* Advanced styling with gradients, frosted glass blur, and borders */
rapi-doc::part(section-navbar) {
  background: linear-gradient(180deg, #0f172a 0%, #020617 100%);
  border-right: 1px solid rgba(255, 255, 255, 0.08);
  backdrop-filter: blur(12px);
}

/_ Sidebar header area (logo and filter input) _/
rapi-doc::part(section-navbar-header) {
border-bottom: 1px solid rgba(255, 255, 255, 0.06);
padding: 16px;
}

Token Renaming: --nav-hover-fg and --nav-accent-fg

The tokens --nav-hover-fg and --nav-accent-fg are the canonical CSS variables for navigation hover text and selected item text color in default left-bar mode. In colored-block mode, selected items use standard --primary and --primary-foreground. Pre-release references to --nav-hover-text, --nav-accent, and --nav-accent-foreground have been completely dropped without backward compatibility.

Sidebar Item Density in v11

To adjust vertical spacing between navigation links in v11 without CSS hacks, use the new declarative attribute: <rapi-doc nav-item-spacing="compact | default | relaxed"></rapi-doc>.

---

3.4 Replacing Typography & Font Attributes

In v10, custom fonts were passed as comma-separated font strings in attributes. In v11, configure fonts using CSS variables, allowing seamless inheritance from your application design system or @font-face definitions.

v10 (Legacy Attributes)

<rapi-doc
  spec-url="https://api.example.com/openapi.json"
  regular-font="'Inter', sans-serif"
  mono-font="'JetBrains Mono', monospace"
  font-size="large"
></rapi-doc>

v11 (CSS Variables & Scale)

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

<rapi-doc
spec-url="https://api.example.com/openapi.json"
scale="lg"

> </rapi-doc>

Font Scaling Mapping Reference

v10 font-size Value	v11 scale Equivalent	Description
default	scale="default"	14px base typography with balanced proportions.
large	scale="lg"	16px base typography, generous margins, and wider sidebar.
largest	scale="lg"	Scaled up for presentations or accessibility.
(New)	scale="sm"	Compact 13px base typography; ideal for embedded console widgets.

---

3.5 Button & Component Styling via ::part()

In v10, you could not customize individual buttons, search bars, or server cards without overriding entire themes. RapiDoc v11 provides W3C standard CSS Shadow Parts for internal elements.

/* Style primary action buttons (TRY, execute, search) */
rapi-doc::part(btn-fill) {
  background: linear-gradient(135deg, #06b6d4 0%, #3b82f6 100%);
  border-radius: 8px;
  box-shadow: 0 4px 12px rgba(6, 182, 212, 0.25);
  font-weight: 600;
}

rapi-doc::part(btn-fill):hover {
  transform: translateY(-1px);
  box-shadow: 0 6px 16px rgba(6, 182, 212, 0.4);
}

/* Style the TRY button specifically */
rapi-doc::part(btn-try) {
  border-radius: 6px;
  font-weight: 700;
  letter-spacing: 0.05em;
}

/* Style server selection panel */
rapi-doc::part(section-servers) {
  background: rgba(15, 23, 42, 0.6);
  border: 1px solid rgba(56, 189, 248, 0.2);
  border-radius: 10px;
}

---

4. End-to-End Migration Examples

Example 1: Corporate Dark Portal

v10 Syntax

<rapi-doc
  spec-url="https://petstore.swagger.io/v2/swagger.json"
  theme="dark"
  bg-color="#0d1117"
  text-color="#c9d1d9"
  header-color="#161b22"
  primary-color="#238636"
  regular-font="'Inter', sans-serif"
  mono-font="'Fira Code', monospace"
  nav-bg-color="#161b22"
  nav-text-color="#8b949e"
  nav-accent-color="#238636"
  font-size="default"
></rapi-doc>

v11 Syntax

<style>
  rapi-doc {
    --background: #0d1117;
    --foreground: #c9d1d9;
    --header-bg: #161b22;
    --font-sans: 'Inter', sans-serif;
    --font-mono: 'Fira Code', monospace;
    --nav-background: #161b22;
    --nav-foreground: #8b949e;
  }
</style>

<rapi-doc
spec-url="https://petstore.swagger.io/v2/swagger.json"
color-scheme="dark"
theme="#238636"
radius="md"
scale="default"

> </rapi-doc>

---

Example 2: Light Mode with Corporate Indigo Accent

v10 Syntax

<rapi-doc
  spec-url="https://petstore.swagger.io/v2/swagger.json"
  theme="light"
  bg-color="#ffffff"
  text-color="#1e293b"
  primary-color="#4f46e5"
  nav-bg-color="#f8fafc"
  nav-text-color="#475569"
  nav-accent-color="#4f46e5"
></rapi-doc>

v11 Syntax

<rapi-doc
  spec-url="https://petstore.swagger.io/v2/swagger.json"
  color-scheme="light"
  theme="#4f46e5"
  radius="md"
></rapi-doc>

(Notice how concise v11 is: color-scheme="light" sets the base surfaces, and theme="#4f46e5" automatically configures navigation accents and high-contrast button labels!)

---

5. Step-by-Step Migration Checklist

Follow these steps to migrate an existing application to RapiDoc v11:

257. Update Package Dependency / CDN Link Upgrade your rapidoc package or update the <script> tag:

     npm install rapidoc@latest

258. Update the Base Surface Mode Search your HTML templates for theme="dark" or theme="light". Change them to:

     • theme="dark" $\rightarrow$ color-scheme="dark"
     • theme="light" $\rightarrow$ color-scheme="light"
     • (Optional) Use color-scheme="system" to automatically match user OS preference.

259. Migrate Primary Brand Colors If you used primary-color="#...", migrate to:

     • <rapi-doc theme="#your-hex-color"> or
     • CSS: rapi-doc { --primary: #your-hex-color; }

260. Convert Deprecated Color Attributes to CSS Variables Remove bg-color, text-color, and nav-* attributes from <rapi-doc>. If you need custom values beyond the built-in presets, define them in CSS:

     rapi-doc {
       --background: #...;
       --foreground: #...;
       --nav-background: #...;
     }

261. Convert Font Attributes to CSS Typography Tokens Remove regular-font and mono-font attributes. Declare them in CSS:

     rapi-doc {
       --font-sans: 'YourFont', sans-serif;
       --font-mono: 'YourMono', monospace;
     }

262. Convert font-size to scale Change font-size="large" to scale="lg".

263. Take Advantage of ::part() for Advanced Customization Replace any awkward styling workarounds with standard CSS Shadow Parts (rapi-doc::part(section-navbar), rapi-doc::part(btn-fill), etc.).

---

Related Documentation

Theming Overview

Learn about all 7 design system presets, custom hex brand colors, and contrast calculations. View Theming Guide

CSS Parts & Variables Reference

Explore the full catalog of CSS Custom Properties and Shadow Parts available in RapiDoc. Explore CSS Parts