From 90ee5da701b1b2732afb70e689ffd6e1ce6a46af Mon Sep 17 00:00:00 2001 From: Eva Sarafianou Date: Wed, 29 Jul 2026 13:01:22 +0300 Subject: [PATCH] docs: fix dark-mode code block contrast issues (#37736) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: fix dark-mode code block contrast, plan plugin SDK reference migration - Change the outgoing webhooks pseudo-JSON example to a `text` fence instead of `json`, since the malformed JSON caused Prism to misinterpret `//` inside a URL as a comment, rendering it as a distracting highlighted link in dark mode. - Restore contrast for Prism's comment token and the active/hover table-of-contents link in dark mode, both of which were nearly invisible against the current dark background colors. - Add a handoff plan for restoring the three plugin SDK reference pages that were left as migration placeholders (previously rendered by Hugo shortcodes parsing live Go/TS source). Co-authored-by: Cursor * docs: remove migration plan doc from this PR The plugin SDK reference migration plan is a separate piece of handoff work, not part of this dark-mode contrast fix — drop it from this PR (kept locally, untracked, for handing off separately). Co-authored-by: Cursor --------- Co-authored-by: Cursor --- .../integrate/webhooks/outgoing/index.md | 2 +- docs/site/src/css/custom.css | 24 ++++++++++++++----- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/docs/develop/integrate/webhooks/outgoing/index.md b/docs/develop/integrate/webhooks/outgoing/index.md index 11d9d948ff9e..5f452417bc1d 100644 --- a/docs/develop/integrate/webhooks/outgoing/index.md +++ b/docs/develop/integrate/webhooks/outgoing/index.md @@ -65,7 +65,7 @@ If you leave the channel field blank, the webhook will respond to trigger words 2. Add a configurable *MATTERMOST_TOKEN* variable to your application and set it to the **Token** value from step 7. This value will be used by your application to confirm the HTTP POST request came from Mattermost. 3. To have your application post a message back to `town-square`, it can respond to the HTTP POST request with a JSON response such as: - ```json + ```text {"text": " | Component | Tests Run | Tests Failed | |:-----------|:----------|:-----------------------------------------------| diff --git a/docs/site/src/css/custom.css b/docs/site/src/css/custom.css index 8c12f0df50e4..eacfa6d94a51 100644 --- a/docs/site/src/css/custom.css +++ b/docs/site/src/css/custom.css @@ -472,11 +472,7 @@ h2, h3, h4 { * so it still needs lightening. #52607A (~2.9:1) is that lighter fill; * denim-400 below gives it a real border. Needed to go further than the * contrast ratio alone suggests — low-luminance colors require a bigger - * jump than the formula implies to look distinct to the eye. Trade-off: - * dracula's comment token (#6272a4, already its dimmest/de-emphasized one) - * loses some contrast against this fill, acceptable since it stays - * distinguishable via italics and this site's examples don't use inline - * comments anyway. */ + * jump than the formula implies to look distinct to the eye. */ .theme-code-block .prism-code { font-size: 0.85rem; background: var(--mm-denim-50) !important; @@ -485,6 +481,17 @@ h2, h3, h4 { background: #52607A !important; } +/* Lightening the dark-mode code block fill above (#52607A) leaves + * dracula's comment token — already its dimmest/de-emphasized color + * (#6272a4) — at only ~1.35:1 contrast against it, i.e. nearly invisible. + * #D3DBF2 restores ~4.6:1 (WCAG AA) while staying a muted blue-lavender, + * distinguishable from the brighter default token colors but still legible. + * !important is required: prism-react-renderer sets each token's color via + * an inline `style` attribute, which otherwise beats this class selector. */ +[data-theme='dark'] .theme-code-block .prism-code .token.comment { + color: #D3DBF2 !important; +} + /* Copy button — denim border, marigold on hover */ .clean-btn[class*="copyButton"] { border: 1px solid var(--mm-border-subtle) !important; @@ -654,9 +661,14 @@ blockquote { padding: 0.4rem 0.75rem 0.4rem 1rem; font-size: 0.82rem; } +/* --mm-color-denim is a fixed brand navy, not a semantic/theme-aware + * token — it never adapts for dark mode. Against the dark page background + * that's only ~1.45:1 contrast, i.e. the active TOC item nearly vanishes. + * --ifm-color-primary is already the theme-aware equivalent (denim in + * light mode, --mm-color-sky in dark, ~12:1 against the dark page). */ .table-of-contents__link--active, .table-of-contents__link:hover { - color: var(--mm-color-denim); + color: var(--ifm-color-primary); font-weight: 600; }