Theming with CSS Variables
Every color, spacing value, and font in the docs layout is controlled by a small set of CSS custom properties (CSS variables), rather than being scattered across the stylesheet. Changing your docs’ appearance means overriding these variables, not editing templates or fighting specificity.
Where to add your overrides#
Go to WP Super Docs → Settings → Custom Code, and add your CSS to the Desktop field (see Custom Head/Body/Footer Code for the full details on that settings tab). This field is output in <head> deliberately late, after the plugin’s own stylesheet, so your values simply win without needing !important or any other override trick.
For the eight main colors you don’t need CSS at all: Settings → Appearance → Colors has a field for each, for light and dark mode (see Customizing Colors and Branding).
The variables#
These are set on :root, so they apply sitewide by default:
| Variable | Default | Controls |
|---|---|---|
--wpsd-bg | #ffffff | Page background |
--wpsd-text | #1f2328 | Main text color |
--wpsd-muted | #6e7781 | Secondary/muted text |
--wpsd-border | #e5e7eb | Borders and dividers |
--wpsd-accent | #d97706 | Links, active states, primary accent |
--wpsd-accent-hover | #b45309 | Accent color on hover |
--wpsd-accent-bg | #fef3c7 | Accent background tint (e.g. active nav item) |
--wpsd-sidebar-bg | #ffffff | Sidebar background |
--wpsd-card-bg | #ffffff | Cards (product/category cards, etc.) |
--wpsd-code-bg | #f3f4f6 | Inline code background |
--wpsd-pre-bg | #1f2328 | Code block background |
--wpsd-pre-text | #f3f4f6 | Code block text |
--wpsd-input-bg | #f9fafb | Search box and form field backgrounds |
--wpsd-hover-bg | #f9fafb | General hover state background |
--wpsd-footer-bg | #f9fafb | Footer background |
--wpsd-content-max | 820px | Max width of doc content |
--wpsd-sidebar-width | 280px | Sidebar width |
--wpsd-shell-max | 1600px | Max width of the whole layout |
--wpsd-topbar-height | 64px | Topbar height |
--wpsd-radius | 8px | Corner rounding, used throughout |
--wpsd-font | System font stack | Base font family |
Dark mode has its own set#
Dark mode (see Light & Dark Mode) doesn’t invert your light colors automatically, it uses a completely separate set of values, scoped to html[data-wpsd-theme="dark"]. The layout variables (--wpsd-content-max, --wpsd-sidebar-width, --wpsd-shell-max, --wpsd-topbar-height, --wpsd-radius, --wpsd-font) aren’t overridden for dark mode, since layout and typography don’t need to change between themes, only color.
To customize dark mode, target the same selector the plugin uses:
:root {
--wpsd-accent: #0d9488;
--wpsd-accent-hover: #0f766e;
--wpsd-radius: 4px;
}
html[data-wpsd-theme="dark"] {
--wpsd-accent: #2dd4bf;
--wpsd-accent-hover: #5eead4;
}
If you only override :root and skip the dark mode block, dark mode keeps its own defaults rather than inheriting your light-mode values, so remember to set both if you want a consistent brand color across both themes.
Docs home variables#
The docs home (the Search hub and Grouped by role layouts) has its own variables, set on .wpsd-home. The Look settings under Settings → Display → Docs home set most of them for you. Your own values in Custom Code win over the Look settings.
| Variable | What it sets |
|---|---|
--wpsd-home-hero-bg |
Hero background color |
--wpsd-home-hero-image |
Hero background image |
--wpsd-home-hero-image-pos |
Which part of the image stays in view |
--wpsd-home-hero-overlay |
Overlay over the image |
--wpsd-home-hero-text |
Heading color in the hero |
--wpsd-home-hero-muted |
Intro and “Try” label color in the hero |
--wpsd-home-hero-accent |
Color of the small label above the heading |
--wpsd-home-hero-border |
Line under the hero |
--wpsd-home-hero-shadow |
Text shadow in the hero |
--wpsd-home-search-shadow |
Shadow around the search box |
--wpsd-home-chip-bg, --wpsd-home-chip-hover, --wpsd-home-chip-text, --wpsd-home-chip-ring |
The “Try” links |
--wpsd-home-space |
Space between sections |
--wpsd-home-radius |
Corner rounding of cards, boxes and the search box |
CSS frameworks#
On sites using a CSS framework like Automatic.css or Core Framework, the docs pages no longer pick up the framework’s section padding. Sections inside your doc content still get the framework’s styles.
Going beyond variables#
You’re not limited to variables, since the Custom CSS field accepts any valid CSS. Anything beyond a variable override (gradients, custom borders, animated effects) is just regular CSS appended after your variable changes, targeting the plugin’s existing class names directly.
Ready-made examples#
If you’d rather start from a finished look than build one from scratch, wpsuperdocs.com/theming has four ready-to-copy themes with side-by-side light and dark screenshots: Ocean (a calm, conventional blue), Neon Pulse (gradient title text and a frosted topbar), Brutalist Mono (monospace, zero radius, heavy borders), and Terminal (a scanline CRT look with a blinking cursor). Each one is just CSS you can copy and paste straight into the Custom CSS field described below.
Using AI to build a theme#
Since every variable is a plain, well-named custom property, you can hand the list above to an AI assistant (ChatGPT, Claude, or similar) along with your brand’s colors, a screenshot, or a plain description, and ask it to write out the overrides for both light and dark mode. Paste whatever it gives you into the Custom CSS field and adjust from there.
wpsuperdocs.com/theming has a ready-to-copy base file with every variable at its default, plus a comment on each line explaining what it controls, and an example prompt you can adapt with your own brand details. Handing an AI the full commented file (rather than just the table above) tends to work better, since it can see exactly what already exists instead of guessing at variable names that were never there.
If a color or value you asked for doesn’t seem to apply, double check that the variable name wasn’t changed or invented, only the exact names listed above are read by the plugin; anything else is silently ignored by the browser rather than causing an error.
Was this helpful?
Thanks for your feedback!
✓ Feedback received. Thank you!