` component renders the surface (`` background, padding, rounded corners) using `--color-wk-bg-elevated` and `--color-wk-text` for the body text, but token-level coloration is delegated to whichever highlighter you wire up.
If you load a syntax-highlighter theme on top of ``, **the theme's per-token colors must meet WCAG 2.1 AA (≥4.5:1) against the active `--color-wk-bg-elevated`, in BOTH light and dark mode, across every theme preset you ship to your users.** This is non-negotiable — code blocks are body text, and 4.5:1 is the threshold.
Two foot-guns to watch for:
1. **Light-mode WCAG overrides that bleed into dark mode.** A common pattern is to load a base highlight.js theme (`github.min.css`) and then override individual `.hljs-*` token colors in your own CSS to hit AA against your light surface. If those overrides are unscoped (e.g. plain `.docs-prose pre .hljs-keyword { color: ... }`), they'll keep winning the cascade against your dark-mode bundle (`github-dark-dimmed.min.css`) too — painting dark light-mode colors onto a dark background. **Always scope WCAG overrides with `html:not(.dark)`** (or your equivalent dark-mode root selector) so they drop out of the cascade in dark mode.
2. **Per-theme `--color-wk-bg-elevated` variations.** Different theme presets ship different elevated-surface tones (Retro Terminal `#1a1a1a`, Cupertino `#2C2C2E`, Default `oklch(20.5% 0 0)` ≈ `#353535`, etc.). A token palette that passes 4.5:1 against one preset's bg-elevated may fail against another. Audit token contrast on every preset × every mode combination, not just one pair.
A practical audit recipe (Playwright + WCAG 2.1 contrast computation):
```js
// pseudo-code: iterate themes × modes × representative pages,
// walk every `.docs-prose pre code.hljs span[class^="hljs-"]`,
// compute getComputedStyle().color vs effective non-transparent
// background, fail the build on any sample below 4.5:1.
for (const theme of THEMES) {
for (const mode of ['light', 'dark']) {
await page.goto(`...`);
await page.evaluate(([t, m]) => {
localStorage.setItem('wirekit-theme', t);
localStorage.setItem('wirekit-dark-mode', m === 'dark' ? '1' : '0');
}, [theme, mode]);
await page.reload();
// ... walk DOM, compute contrast, exit non-zero on failure
}
}
```
If you ship syntax-highlighted code blocks in your own developer app, wire an equivalent contrast audit into your CI — walk every theme × mode × representative page, compute foreground-vs-background contrast for every `.hljs-*` token-class, and fail the build below the WCAG 4.5:1 threshold for normal text.
## Design Token Reference
The complete CSS-variable surface — every `--color-wk-*`, `--radius-wk-*`, `--shadow-wk-*`, motion / typography / sizing token, plus the reading-* component family and chart-theming palette — lives on its own dedicated page so this guide can stay focused on setup and theming concepts.
→ **[Design Tokens](/theming/design-tokens)** — full reference
---
The token surface is intentionally orthogonal to the theme presets above: change a preset to swap visual style, change a token to fine-tune a specific dimension across every component that reads from it.