Docs Callouts That Don’t Betray You: CSS Variables, Dark Mode, and Operational Discipline

What callouts actually do (and why ops should care)

In docs, admonitions are the UI equivalent of guardrails. They’re not decoration; they’re control surfaces. A NOTE says “don’t be surprised.” A TIP says “do this to go faster.” A WARNING says “you can hurt yourself.” A DANGER says “you can hurt everyone else.”

That’s the intent. The reality is uglier: most callouts are implemented as a markdown extension that maps to a CSS class, then themed by whatever happened to be in the design system that week. In light mode they look fine; in dark mode they become low-contrast mush, or worse, the severity ladder flips. Users stop trusting the visuals and skim past the text. When people don’t trust the interface, they do what tired operators always do: they guess.

CSS variables (custom properties) are the best tool we have for making callouts consistent across frameworks, pages, and modes. Not because they’re trendy, but because they give you:

• One place to define meaning (tokens), many places to consume it (components).
• Runtime switching (dark mode, high-contrast mode) without recompiling CSS.
• Safe fallbacks when a token is missing or overridden by some “helpful” theme package.

There’s a reliability mindset here: your docs UI should degrade safely. If a variable is missing, you want a boring default, not an invisible border and gray-on-gray text.

One paraphrased idea worth keeping in your head: Paraphrased idea: “Everything fails; design so it fails safely.” — attributed to John Allspaw’s reliability thinking

Joke #1: Dark mode is like RAID—everyone wants it, and someone will still configure it wrong.

Facts and history you can use in meetings

These aren’t trivia for trivia’s sake. They’re ammunition for the “why are we spending time on callout theming?” conversations.

1. “Admonition” markup predates most modern doc tools. Sphinx popularized directives like .. note:: years before today’s markdown-driven stacks normalized it.
2. GitHub-flavored Markdown didn’t standardize admonitions. Many ecosystems implemented their own syntax, which is why portability is still a mess.
3. CSS custom properties shipped broadly in 2017-era browsers. That matters because “we can’t rely on variables” is usually outdated institutional memory.
4. prefers-color-scheme became practical only after OS-level dark mode adoption. Before that, many sites used a manual toggle and cookie persistence hacks.
5. Early dark themes often inverted colors. Inversion breaks semantic colors: yellow warnings become unreadable, blues become neon, and grays get weird. Modern theming adjusts luminance, not just hue.
6. WCAG contrast guidance is about text legibility, not brand vibes. “It looks fine on my MacBook” is not a contrast strategy.
7. Callout colors have cultural baggage. Red signals danger in many places, but not all. That’s why iconography and labels matter.
8. Design tokens emerged from large-scale multi-platform UI systems. The point was consistency across web/iOS/Android, not just “cleaner CSS.”

Design tokens with CSS variables: the sane approach

Stop thinking of callouts as “a blue box” or “a yellow box.” Think in tokens: accent, background, border, and sometimes icon color. Tokens represent meaning, not implementation.

Token hierarchy you actually want

A reliable hierarchy prevents “random override wars”:

• Global base tokens: --bg, --fg, --border.
• Semantic tokens: --note-accent, --warn-bg, etc.
• Component tokens: --callout-accent, --callout-border set by the component class.

This matters because components should consume semantic tokens, not raw hex values. When you change your warning color once, the entire site should follow. The CSS above does exactly that by mapping .callout.warn to --warn-*.

Fallbacks: what happens when the token is missing?

In production systems, you plan for missing dependencies. Same here. Use fallbacks aggressively:

• border: 1px solid var(--callout-border, var(--border)); means “if callout border missing, use global border.”
• Never rely on background alone for meaning. Borders and titles survive more theme collisions.
• Make the label text (“WARNING”, “DANGER”) a first-class UI element, not a pseudo-element that gets lost with font overrides.

Where tokens should live

Put tokens as close to the document root as possible (:root). If your framework scopes styles, ensure tokens are still globally accessible, or intentionally scoped per docs area. Mixing scoping models is how you get callouts that render differently in the sidebar vs main content.

Dark mode without visual lies

Dark mode theming is not “invert and hope.” Your eyes adapt differently in low light, and your colors behave differently against near-black backgrounds. The main failure mode: you keep the same accent colors but drop the background to a low-opacity tint, and suddenly the label text is the only thing readable. Users interpret the whole box as “low priority,” because it visually recedes.

Use color-scheme and let the platform help

Set color-scheme: light dark at the root. This signals form controls and scrollbars to match. It also reduces the chance that a native control inside a callout looks like it teleported from 2009.

Pick a strategy: tint backgrounds, then correct borders and text

In dark mode, backgrounds should generally be tinted (low alpha) and borders should be stronger than you think. Borders define shape when everything else is dark. That’s why the sample CSS uses:

• --*-bg: rgba(...,.10) for soft fills
• --*-border: rgba(...,.35) for shape and severity cues

Don’t trust your monitor. Instrument your theme.

Yes, you should do visual QA. But you should also treat CSS variables as configuration and verify them in CI. If your theme package updates and silently changes --warn-accent, you want a diff that fails a build, not a customer complaint that “the warning boxes look… chill.”

Joke #2: The only thing darker than dark mode is the soul of the person who merged “quick contrast fix” directly to main.

Implementation patterns for admonitions

Your doc generator might be Markdown, MDX, AsciiDoc, reStructuredText, or something internally cursed. The patterns below survive tool churn.

Pattern A: semantic HTML + classes

Render admonitions as a real element with a title. Avoid pseudo-elements for critical text; they’re fragile for accessibility tooling and translation.

cr0x@server:~$ cat ./callout-example.html
<div class="callout warn" role="note" aria-label="Warning callout">
  <div class="icon" aria-hidden="true"></div>
  <div>
    <div class="title">WARNING</div>
    <p>Do not run this command against production.</p>
  </div>
</div>

Decision: if your pipeline can’t emit semantic HTML like this, fix the pipeline. Styling is the easy part; reliable structure is the hard part.

Pattern B: data attributes for severity

When docs are generated from content, data attributes can reduce class proliferation:

• <aside class="callout" data-kind="warn">
• CSS: .callout[data-kind="warn"] { ... }

This also makes it easier to query in tests.

Pattern C: one callout component, many themes

If you have multiple products or “spaces,” don’t fork the callout CSS. Keep one component. Override tokens per space.

Example approach:

• :root[data-space="storage"] { --note-accent: ... }
• :root[data-space="compute"] { --note-accent: ... }

Operationally, this is how you avoid the “WARN looks different on product A” support ticket spiral.

Pattern D: forced-color and high-contrast support

Windows forced-colors mode will ignore your beautiful palette. Good. You want the OS to win. Add minimal rules:

• @media (forced-colors: active) { .callout { border: 1px solid CanvasText; } }
• Ensure titles remain visible without background reliance.

Accessibility: contrast, semantics, and “don’t rely on color”

Accessibility is not a compliance tax; it’s how you keep meaning intact under hostile conditions: cheap monitors, bright sunlight, migraine mode, or someone reading at 03:00 on a dimmed laptop while babysitting an incident.

Contrast: test the text, not the vibe

For callouts, focus on:

• Title contrast against the callout background.
• Body text contrast against the callout background.
• Border visibility against the page background.

A common trap: you meet contrast on the title but fail it on links inside the callout because link color is global. That’s why tokens should consider link contrast too (or at least avoid ultra-light background tints that wash links out).

Semantics: keep the label and severity machine-readable

Use a visible label and consider aria-label. A screen reader should not have to infer that a border is yellow. Humans shouldn’t either.

Don’t encode severity solely by color

Use at least two cues:

• Label text: NOTE/TIP/WARNING/DANGER.
• Icon shape (even if it’s simple).
• Border thickness or pattern (subtle but helpful).

Three corporate mini-stories from the theming trenches

Mini-story #1: an incident caused by a wrong assumption

A mid-sized company migrated their internal docs to a new static site generator. The content owners were happy: faster builds, prettier pages, a dark mode toggle. Engineering leadership approved it because “it’s docs, not production.”

The migration included admonitions. The old system rendered WARNING and DANGER with different icons and very distinct borders. The new system used the same icon for both, and the theme author assumed the red tint background would be “obviously danger.” In light mode, it mostly was. In dark mode, the backgrounds were low-opacity tints and the page background was a near-black that swallowed the difference.

A month later, someone followed a runbook to rotate credentials for a shared integration. There was a DANGER callout: “This step invalidates tokens for all environments; coordinate.” In dark mode, it looked like a mild warning, the person assumed it was localized impact, and they proceeded solo.

Result: multiple services lost auth within minutes. The incident was not caused by bad authentication design; it was caused by a wrong assumption about how a UI communicates risk. The post-incident fix was not “train engineers to read better.” It was: enforce severity differentiation via tokens, add automated contrast checks, and require unique icons for WARNING vs DANGER.

Mini-story #2: an optimization that backfired

Another org decided their CSS bundle was too large. Someone proposed “optimizing” by removing semantic tokens and letting the build pipeline inline hex colors directly into component CSS. Fewer variables, fewer bytes, faster page loads. The performance dashboard improved a little, which is how these ideas get promoted.

Then a brand refresh happened. The design system updated accent colors. Most components picked up the new palette because they were token-based. But admonitions were now hard-coded in compiled CSS. Half the pages had the old colors and half had the new. In dark mode, the new palette worked; the old palette didn’t. Users began reporting that WARNING boxes were unreadable—only on certain doc sections.

The team spent days chasing “caching issues” and “CDN propagation.” The reality was more embarrassing: the optimization removed the single point of truth. The fix was to restore CSS variables, accept a slightly larger CSS file, and put real budgets in place: measure bundle size, but don’t micro-optimize away maintainability.

They also learned the hard lesson: a smaller CSS file is not “faster” if it triggers more human time and more production mistakes. Latency is not only measured in milliseconds.

Mini-story #3: a boring but correct practice that saved the day

A large enterprise team maintained docs for a storage platform with lots of “you can delete everything” commands. Their docs were treated as part of the product, which meant changes ran through CI with tests. Not flashy. Very effective.

They had a rule: tokens for callouts live in one file, and every change to that file triggers a visual regression run plus a simple “token presence” test. They also kept a tiny page called “severity ladder” that rendered all four callouts, with links and code blocks, in both modes.

One day a dependency update changed a base background token. It wasn’t malicious; it was a refactor. The callouts still rendered, but the WARNING border contrast dropped and the DANGER background became too subtle. The visual regression job flagged it before merge.

No drama, no late-night rollback. The fix was a small adjustment to the dark-mode border alpha. This is what “boring correctness” buys you: you catch semantic regressions early, and your docs don’t quietly teach people the wrong thing.

Practical tasks: commands, outputs, and decisions

Docs theming issues are best debugged like any other production issue: reproduce, measure, isolate, fix, verify, then prevent regressions. These tasks assume a typical static docs repo with a build output directory (for example build/ or dist/), CSS assets, and a local dev server.

Task 1: Find where admonitions are rendered in the output HTML

cr0x@server:~$ rg -n "callout|admon|alert|data-kind" build/ -S | head
build/ops/runbook/index.html:214:<div class="callout warn" role="note" aria-label="Warning callout">
build/ops/security/index.html:88:<aside class="callout" data-kind="danger">
build/styles/main.css:1023:.callout.warn{--callout-accent:var(--warn-accent);}

What it means: You now know the actual DOM shape and selectors used in production output.

Decision: If output varies by page (div vs aside), standardize it. Inconsistent markup guarantees inconsistent styling and testing.

Task 2: Locate the token definitions and confirm they’re not duplicated

cr0x@server:~$ rg -n --hidden --glob '!**/node_modules/**' ":root|--note-accent|--warn-accent|--danger-accent" .
./src/styles/tokens.css:1::root{
./src/styles/tokens.css:22:  --note-accent: #2563eb;
./src/styles/tokens.css:30:  --warn-accent: #b45309;
./src/styles/tokens.css:38:  --danger-accent: #dc2626;
./src/styles/theme-overrides.css:11::root{ --warn-accent: #a16207; }

What it means: You have multiple definitions; last one wins at runtime.

Decision: Consolidate tokens or document override precedence. If you can’t explain precedence in one sentence, you don’t control it.

Task 3: Verify dark mode is driven by prefers-color-scheme and not a brittle class toggle

cr0x@server:~$ rg -n "prefers-color-scheme|data-theme=|class=.*dark" src/styles -S
src/styles/tokens.css:45:@media (prefers-color-scheme: dark){
src/styles/app.css:12:html[data-theme="dark"] .sidebar{ background: #0b1020; }

What it means: You’re mixing automatic and manual dark mode.

Decision: Choose one source of truth. If you support a manual toggle, it should override prefers-color-scheme intentionally (and consistently).

Task 4: Start a local server and reproduce in both modes

cr0x@server:~$ npm run dev
> docs@1.0.0 dev
> vite

  VITE v5.4.0  ready in 430 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.1.20:5173/

What it means: You have a reliable reproduction environment.

Decision: If you cannot reproduce locally, don’t “fix” production CSS. First align build environments (Node version, lockfile, CI).

Task 5: Confirm the final computed variables in the built CSS

cr0x@server:~$ rg -n --no-heading --fixed-strings "--warn-bg" build/assets/*.css | head -n 5
build/assets/main-9a8c1.css:1:...--warn-bg:#fffbeb;--warn-border:#fde68a;...
build/assets/main-9a8c1.css:1:...@media (prefers-color-scheme:dark){:root{--warn-bg:rgba(251,191,36,.1);--warn-border:rgba(251,191,36,.35)}}

What it means: Tokens exist in output and have both light and dark values.

Decision: If dark overrides are missing, your CSS build may be tree-shaking or scoping away media blocks. Fix bundler config before tweaking colors.

Task 6: Check whether the callout selector is being overridden later in CSS order

cr0x@server:~$ rg -n "\.callout\.warn|\[data-kind=\"warn\"\]" build/assets/*.css | head -n 20
build/assets/main-9a8c1.css:1023:.callout.warn{--callout-accent:var(--warn-accent);--callout-bg:var(--warn-bg);--callout-border:var(--warn-border)}
build/assets/vendor-a12ff.css:887:.callout{border:1px solid transparent;background:transparent}

What it means: Vendor CSS may be resetting your callout component after your own rules, depending on load order.

Decision: Fix load order or increase specificity carefully. Do not start a specificity arms race; you’ll lose and you’ll deserve it.

Task 7: Sanity-check for missing tokens using a quick grep list

cr0x@server:~$ rg -o --no-filename "var\\(--[a-z0-9-]+\\)" -S src/styles | sort | uniq | head -n 20
var(--bg)
var(--border)
var(--callout-accent)
var(--callout-bg)
var(--callout-border)
var(--danger-accent)
var(--danger-bg)
var(--danger-border)
var(--fg)
var(--link)
var(--muted)
var(--note-accent)
var(--note-bg)
var(--note-border)
var(--tip-accent)
var(--tip-bg)
var(--tip-border)
var(--warn-accent)
var(--warn-bg)
var(--warn-border)

What it means: You have an inventory of variables referenced.

Decision: Compare this to what you define in :root. Missing definitions should be treated as build failures, not “it seems fine.”

Task 8: Detect undefined variables by searching for fallbacks missing

cr0x@server:~$ rg -n "var\\(--(note|tip|warn|danger)-[a-z-]+\\)" src/styles | head
src/styles/callouts.css:14:background: var(--warn-bg);
src/styles/callouts.css:15:border-color: var(--warn-border);

What it means: These references have no fallback. If tokens are missing or scoped out, you get broken visuals.

Decision: For critical semantics (WARN/DANGER), add fallbacks or enforce token presence via tests (prefer tests).

Task 9: Verify the HTML includes labels and not just icons

cr0x@server:~$ rg -n "WARNING|DANGER|TIP|NOTE" build/ops -S | head
build/ops/runbook/index.html:216:<div class="title">WARNING</div>
build/ops/runbook/index.html:301:<div class="title">DANGER</div>

What it means: Severity is present as text in the DOM.

Decision: If labels are missing, add them at render time. Styling can change; text is durable.

Task 10: Create a “severity ladder” page and ensure it builds

cr0x@server:~$ ls -la src/pages/severity-ladder.md
-rw-r--r-- 1 cr0x cr0x 1482 Dec 28 10:22 src/pages/severity-ladder.md

What it means: You have a single page that renders all callout states for QA and visual regression.

Decision: If you don’t have this page, create it. It’s the canary for theming regressions.

Task 11: Confirm CI builds the same output locally (lockfile sanity)

cr0x@server:~$ node --version
v22.11.0

What it means: Node version is explicit.

Decision: Pin Node versions in CI. CSS output differences due to tooling versions are real, and they are a stupid way to spend a Wednesday.

Task 12: Inspect bundle composition to see where callout CSS lands

cr0x@server:~$ ls -lh build/assets | head
total 1.6M
-rw-r--r-- 1 cr0x cr0x  92K Dec 28 10:35 main-9a8c1.css
-rw-r--r-- 1 cr0x cr0x 610K Dec 28 10:35 vendor-a12ff.css
-rw-r--r-- 1 cr0x cr0x 120K Dec 28 10:35 main-9a8c1.js
-rw-r--r-- 1 cr0x cr0x 740K Dec 28 10:35 vendor-a12ff.js

What it means: CSS is split; load order matters.

Decision: Ensure token definitions load before components, and components before overrides. If your bundler reorders, you need explicit imports.

Task 13: Detect accidental duplication of callout CSS across bundles

cr0x@server:~$ for f in build/assets/*.css; do echo "== $f"; rg -n "\.callout(\.|\[)" "$f" | head -n 3; done
== build/assets/main-9a8c1.css
1023:.callout.warn{--callout-accent:var(--warn-accent);--callout-bg:var(--warn-bg);--callout-border:var(--warn-border)}
1030:.callout.danger{--callout-accent:var(--danger-accent);--callout-bg:var(--danger-bg);--callout-border:var(--danger-border)}
== build/assets/vendor-a12ff.css
887:.callout{border:1px solid transparent;background:transparent}

What it means: You have base callout styling in vendor, and severity mapping in main.

Decision: That can be fine, but document it. If vendor changes, your component behavior changes. Consider pulling base callout styles into your own bundle for stability.

Task 14: Verify that link colors inside callouts remain readable in both modes

cr0x@server:~$ rg -n "a\\{|--link" src/styles -S
src/styles/tokens.css:14:  --link: #0b5fff;
src/styles/tokens.css:15:  --link-visited: #6a2cff;
src/styles/app.css:66:a{ color: var(--link); }

What it means: Links are token-based, so you can tune them globally if callout backgrounds change.

Decision: If links are hard-coded, move them to tokens. Callouts are where people click “Learn more” right before doing the risky thing.

Fast diagnosis playbook

When someone reports “callouts are wrong in dark mode,” you want to find the bottleneck fast. Not elegantly. Fast.

First: confirm the symptom is semantic, not aesthetic

• Are WARNING and DANGER distinguishable at a glance?
• Is the label visible?
• Is body text readable without zooming?

Why: If semantics are intact, you can schedule a polish fix. If semantics are broken, treat it as a high-priority defect.

Second: identify the source of truth for theme state

• Is dark mode driven by prefers-color-scheme?
• Is there a manual toggle (data-theme, a class on html)?
• Are both active and fighting?

Why: “Dark mode is wrong” is often “we have two dark modes.”

Third: verify token presence and override order

• Are --warn-* and --danger-* defined in :root?
• Do the dark-mode overrides exist in the final CSS?
• Is vendor CSS resetting the callout component after your rules?

Why: If tokens are correct but the component is overridden later, your fix is ordering, not color selection.

Fourth: check for scoping bugs

• Are tokens defined under a container that doesn’t include the docs content?
• Are admonitions rendered in an iframe or shadow root?

Why: CSS variables inherit. If your callouts aren’t inside the scope, they don’t get values.

Fifth: run a targeted visual regression on the severity ladder page

• Compare light vs dark screenshots
• Diff the CSS token file

Why: Visual regressions are easy to argue about. Diffs are not.

Common mistakes: symptom → root cause → fix

1) Symptom: DANGER looks like NOTE in dark mode

Root cause: Dark mode uses low-opacity tints for all callouts, but accents are too similar in luminance. Or the border alpha is too low to read against the page background.

Fix: Increase border contrast for higher severities. Make DANGER border stronger than WARNING. Consider adding a subtle left border or thicker border for DANGER only.

2) Symptom: Callout background disappears on some pages

Root cause: Tokens are scoped to a container that isn’t present on those pages (for example, tokens set on .docs-layout but landing pages use .marketing-layout).

Fix: Move semantic tokens to :root or ensure both layouts inherit from a shared root wrapper.

3) Symptom: Borders are transparent even though CSS sets them

Root cause: Another stylesheet later in the cascade sets .callout { border-color: transparent; } or resets borders.

Fix: Fix import order. If you can’t, make the component rule more specific in a controlled way (for example main .callout), not with !important everywhere.

4) Symptom: Only the icon is colored; everything else is gray

Root cause: The component only applies --callout-accent and not background/border tokens, or the mapping from severity class to tokens is missing.

Fix: Map each severity to all three tokens: accent, background, border. Partial theming is how you get ambiguous UI.

5) Symptom: Links in callouts are unreadable in dark mode

Root cause: Global link tokens were designed for page background, not tinted callout backgrounds; contrast drops inside callouts.

Fix: Either tune global link tokens or set a callout-specific link token, e.g. .callout a{ color: var(--callout-link, var(--link)); }, with per-severity overrides if needed.

6) Symptom: Print/PDF output loses severity distinctions

Root cause: Reliance on background tints and color-only meaning; print styles often disable backgrounds.

Fix: Add print CSS: keep borders, keep labels, and consider patterned borders (solid vs double) for high severity.

7) Symptom: Admonitions look different between MDX pages and markdown pages

Root cause: Different renderers emit different HTML, so your selectors match one and not the other.

Fix: Normalize output in the renderer layer, or write selectors to cover both structures intentionally (and test them).

8) Symptom: Dark mode toggle works, but callouts don’t change

Root cause: Tokens are only set in @media (prefers-color-scheme: dark), but your toggle uses html[data-theme="dark"].

Fix: Mirror overrides under both mechanisms, or better: unify on one method. If you must support both, implement: “toggle wins over media query.”

Checklists / step-by-step plan

Step-by-step: build callouts that survive theme churn

1. Standardize markup: one DOM shape for all admonitions (including title label) across all content types.
2. Define base tokens at :root: background, foreground, borders, link colors.
3. Define semantic severity tokens: --note-*, --tip-*, --warn-*, --danger-*.
4. Map severity to component tokens in the callout component: set --callout-accent, --callout-bg, --callout-border.
5. Implement fallbacks at the component consumption point (borders, background) so missing tokens degrade safely.
6. Support dark mode with explicit overrides under @media (prefers-color-scheme: dark) and/or your chosen toggle mechanism.
7. Add a severity ladder page that renders all severities with links and code blocks.
8. Add a “token presence” CI check: parse CSS or grep the built output for required tokens.
9. Add visual regression tests for the ladder page in light and dark modes.
10. Define review rules: any change to tokens requires a screenshot diff and contrast verification.

Operational checklist: before you merge a theme change

• WARNING and DANGER are visually distinct in both modes without reading the body text.
• Labels are present and readable.
• Links inside callouts remain readable and obviously links.
• Print styles preserve borders and labels.
• Vendor CSS updates cannot override tokens silently (import order verified).
• Dark mode state has one source of truth (or a documented precedence rule).
• Severity ladder page passes visual regression diff checks.

FAQ

1) Should callouts use <aside> or <div>?

Use <aside> when the content is tangential to the main flow (which many callouts are). Use <div> if your generator can’t reliably emit <aside>. Consistency matters more than semantic perfection.

2) Should I theme callouts with hex colors or HSL?

Use whatever your team can maintain. HSL can make luminance adjustments easier for dark mode, but only if your team actually uses it. Tokens are the important part, not the color format.

3) Is prefers-color-scheme enough, or do I need a manual toggle?

For public docs, prefers-color-scheme is a solid default. A manual toggle is helpful when people work in mixed environments (presentations, screen sharing) or when OS settings are locked down. If you add a toggle, make it override the media query predictably.

4) How do I prevent a dependency update from breaking callout colors?

Two controls: (1) keep your tokens in your repo, not inside a vendor theme you don’t control; (2) add visual regression and token presence checks in CI. Treat token changes like API changes.

5) Why not just use !important to stop overrides?

Because you’ll win the battle and lose the war. !important scales badly and breaks theming extensibility. Fix ordering and scoping first. If you must use it, apply it to tokens at the root, not to every property on every component.

6) Do callouts need different icons per severity?

Yes, if you want users to differentiate severity quickly. At minimum, WARNING and DANGER should not share the same icon. Pair icon + label + color for redundancy.

7) What’s the minimum test coverage for callouts?

At least one page that renders all severities, in both light and dark modes, under visual regression. Add a quick text-based check that tokens exist in built CSS. It’s cheap and catches the “token file not imported” class of failures.

8) How do I handle callouts inside nested containers (tabs, accordions, sidebars)?

Ensure variables are defined at :root or inherited into those containers. Avoid scoping tokens to a layout wrapper that some pages don’t use. If a container deliberately changes background, consider container-specific adjustments via additional tokens (but keep the severity mapping consistent).

9) Are tinted backgrounds required for callouts?

No. Borders plus a strong label can be enough, and often print better. Background tints are a readability aid, not the primary severity signal.

10) How do I keep callouts consistent across multiple doc sites?

Ship a single callout component CSS and a token file. Allow each site to override tokens, not component rules. That’s how you get brand flexibility without semantic drift.

Conclusion: next steps that stick

If you want callouts that don’t betray you, treat them like an operational interface, not a decoration. You’re encoding risk. Make that encoding stable.

1. Normalize admonition markup so your selectors aren’t guessing.
2. Move severity colors into CSS variables (semantic tokens), and map them into a single callout component.
3. Implement dark mode as explicit token overrides, not as accidental side effects.
4. Add a severity ladder page and make it part of CI with a visual diff.
5. Adopt a boring rule: token changes require review like code changes, because they are.

When your docs UI communicates risk correctly, users make fewer guesses. Fewer guesses means fewer incidents. The math is rude but consistent.