docs: enable dark mode behind theme toggle (default stays light)#391
Conversation
- Add light/dark logo pair and dark background (#111113, brand grey-dark scale) - Add html.dark overrides for tables, tinker-box, button border, hero bot - Keep default appearance light; dark is opt-in pending brand/design review
- add dark-recolored variants for the four homepage card svgs (o11y, chromium, auth, stealth) so cream/tan/green tiles no longer blast on the dark page bg - add dark-recolored tinker-bot variant and drop the filter: invert() hack on style.css - swap variants under html.dark via content: url(...) so index.mdx stays untouched and light mode is byte-for-byte identical contrast on #111113: body #EDEEF0 ~16:1, accent #CAB168 ~9:1 (WCAG AAA).
the cream/green/tan card tiles read as framed illustrations on a dark page, not as page leakage. keeping them aligns with how the kernel.sh brand handles illustrations (always light surface) and avoids the visual inconsistency of charcoal-everything-except-chromium-green. tinker-bot keeps its dark-recolored variant: it's a flat silhouette with no card frame, so it actually disappears against #111113 — that swap is a readability fix, not a brand call.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
…ewrite
mintlify rewrites img srcs at deploy time to a cdn url with query params
(/{deployment}/{hash}/images/tinker-bot.svg?fit=max&auto=format&...), so
the prior [src$="..."] suffix selector never matched in production and
the dark recolor swap silently no-op'd. [src*="..."] handles both raw
and rewritten srcs.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
dark mode foundation was off-system. swap to the canonical kernel tokens: - background color #111113 -> #212225 (kernel charcoal / grey-dark-03, the brand's canonical dark background) - white-alpha rgba(255,255,255,...) -> grey-dark-12 alpha rgba(237,238,240,...) across table fills, borders, hovers, and the tinker-box border (kernel brand book lists white as "rare; prefer beige/grey-dark-12") - pricing button border #fff -> #EDEEF0 (grey-dark-12) wcag aaa still holds on the new bg: body 13.7:1, gold 7.57:1, green 6.35:1. intentionally untouched in this commit: - the comment reference to #111113 in the hero-bot rule (stale but cosmetic; will sweep separately if needed)
There was a problem hiding this comment.
Risk assessment: Low risk.
The current diff is limited to Mintlify docs presentation: docs.json theme configuration, dark-mode CSS overrides in style.css, and SVG assets for dark-mode imagery/logos. The update since the prior approval only adjusts dark background/border token values and does not expand the touched surface area.
I found no CODEOWNERS file in the repo. The PR is already approved, so I’m leaving the existing approval in place rather than adding another approval.
Sent by Cursor Automation: Assign PR reviewers
the hero-bot rule's explanatory comment still referenced #111113 after the brand-alignment swap to #212225. cosmetic only, no behavior change.
There was a problem hiding this comment.
Risk assessment: Low risk.
The current diff is limited to the Mintlify docs site's presentation layer: docs.json theme/logo/background configuration, dark-mode CSS overrides in style.css, and static SVG assets for dark-mode logo/hero imagery. There are no production application code, infrastructure, auth, data, or shared-library changes. The latest synchronize update only changes a CSS explanatory comment, so it does not increase risk from the prior assessment.
I found no CODEOWNERS file in the PR head. The PR is already approved, so I’m leaving the existing approval in place rather than approving again.
Sent by Cursor Automation: Assign PR reviewers
the existing style.css uses single-line terse comments (/* table headers */, /* tinker box responsive layout */). the dark-mode block had multi-line essay comments restating what the selectors already say. cropped to match.
There was a problem hiding this comment.
Risk assessment: Low risk.
The current diff is limited to the Mintlify docs site's presentation layer: docs.json theme/logo/background configuration, dark-mode CSS overrides in style.css, and static SVG assets for dark-mode logo/hero imagery. There are no production application code, infrastructure, auth, data, or shared-library changes.
The latest synchronize update only shortens CSS comments in style.css, so it does not increase risk from the existing approval. I found no CODEOWNERS file in the repo. The PR is already approved, so I’m leaving the existing approval in place rather than approving again.
Sent by Cursor Automation: Assign PR reviewers
mintlify's default warning renders as bright yellow on amber-brown, all non-kernel-palette colors. eric flagged it as "harsh on the eyes." swap to: - panel bg/border: grey-dark-12 alpha tints (matches our table treatment) - icon: kernel gold #CAB168 (the brand's only approved warm accent) light mode unchanged. only the yellow Warning class is targeted — Note/Info (blue) and Tip (green) stay mintlify-default for now. note: text color inside the callout still uses mintlify's #9F9F9F since no kernel token cleanly matches a dark-mode mid-gray. follow-up to formalize a dark-mode neutral text token in BRAND.md.
There was a problem hiding this comment.
Risk assessment: Low risk.
I re-evaluated the current diff (f02e46f...0ac9d4b) from the changed files and hunks only. The PR is still limited to Mintlify docs presentation changes: docs.json theme/logo/background configuration, dark-mode CSS overrides in style.css, and static SVG assets for dark-mode imagery. There are no production application code, infrastructure, auth, permissions, data, or shared-library changes.
I found no CODEOWNERS file in the PR head, and docs.json validates as JSON. The PR is already approved, so I’m leaving the existing approval in place rather than approving again.
Sent by Cursor Automation: Assign PR reviewers
matches the existing single-line comment style in the file (/* tinker box border */, /* hero bot dark recolor */, etc).
There was a problem hiding this comment.
Risk assessment: Low risk.
I re-evaluated the current diff (f02e46f...470caf9) from the changed files and hunks only. The PR remains confined to the Mintlify docs site's presentation layer: docs.json theme/logo/background configuration, dark-mode CSS overrides in style.css, and static SVG assets for the dark logo and tinker-bot. There are no production application code, infrastructure, auth, permissions, data, or shared-library changes.
I found no CODEOWNERS file in the repo. The PR is already approved, and this synchronize update does not increase risk, so I’m leaving the existing approval in place rather than approving again.
Sent by Cursor Automation: Assign PR reviewers
the dark-mode logo is the brand book's "white monochrome" variant. naming it light.svg made docs.json line read "dark": "/logo/light.svg", which clashes with the eye. rename closes the cognitive nit and aligns the file name with the brand book's own terminology.
There was a problem hiding this comment.
Risk assessment: Low risk.
I re-evaluated the current diff (f02e46f...51766d) from the changed files and hunks only. The PR remains limited to Mintlify docs presentation changes: docs.json enables the theme toggle/default-light logo/background configuration, style.css adds dark-mode visual overrides, and the new SVG files provide dark-mode static assets. There are no production application code, infrastructure, auth, permissions, data, or shared-library changes.
I found no CODEOWNERS file in the repo. The PR is already approved and this update does not increase risk, so I’m leaving the existing approval in place rather than approving again.
Sent by Cursor Automation: Assign PR reviewers
|
Firetiger deploy monitoring skipped This PR didn't match the auto-monitor filter configured on your GitHub connection:
Reason: This PR modifies documentation styling (dark mode theme for docs site) which is not a service-level change requiring deploy monitoring; clarify if this impacts a monitored service like kernel's website infrastructure. To monitor this PR anyway, reply with |
There was a problem hiding this comment.
Risk assessment: Low risk.
I assessed the current diff (f02e46f...51766d) from the changed files and hunks only. The PR remains limited to Mintlify documentation presentation: docs.json enables a non-strict theme toggle while keeping the default light theme, style.css adds dark-mode visual overrides, and the new SVG files are static dark-mode assets. There are no production application code, infrastructure, auth, permissions, data, or shared-library changes.
I found no CODEOWNERS file in the repo, and docs.json parses successfully as JSON. The PR is already approved, and this update does not increase risk, so I’m leaving the existing approval in place rather than approving again.
Sent by Cursor Automation: Assign PR reviewers
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 51766d4. Configure here.
| } | ||
| html.dark .callout[class*="yellow"] svg { | ||
| color: #CAB168 !important; | ||
| } |
There was a problem hiding this comment.
Warning callout selector misses amber
Medium Severity
Dark-mode Warning callout overrides use a selector that matches class names containing yellow, but Mintlify’s Warning callout is styled with Tailwind amber utility classes. Those rules never apply, so Warning panels and icons keep Mintlify’s default harsh amber styling in dark mode instead of the intended brand tints and gold icon.
Reviewed by Cursor Bugbot for commit 51766d4. Configure here.
masnwilliams
left a comment
masnwilliams
left a comment
There was a problem hiding this comment.
reviewed — looks good, ships clean. light mode is untouched (all overrides are html.dark-scoped), and i verified both new SVGs are fill-only recolors of the existing black.svg / tinker-bot.svg (identical path geometry). couple of non-blocking notes:
nits
style.css:223— the warning-callout fix keys off[class*="yellow"], a substring match on mintlify's internal class names. if they rename/hash those classes the override silently stops applying and the callout reverts to the harsh default with no error. brittle by necessity, worth a heads-up comment.style.css:186,195vs:225— alpha written as0.1in some rules and0.10in others (same value). standardizing on0.10would match the "surface depth scale" in the PR description.logo/white.svg— fill is#EDEEF0, not literal white; name follows the brand-book "white monochrome" term per the description, so fine — just flagging the name/color mismatch.
approving — nothing blocking.
- standardize alpha values to 2-decimal form (0.1 → 0.10) so the surface depth scale reads uniformly (0.02 / 0.04 / 0.08 / 0.10 / 0.14) - add comment above warning callout block noting the selector depends on mintlify's yellow-* tailwind classes and silently no-ops if renamed
There was a problem hiding this comment.
Risk assessment: Low risk.
I evaluated the current diff (f02e46f...c2c2cb6) from the changed files and hunks. The PR remains limited to Mintlify docs presentation changes: docs.json enables the theme toggle while keeping light as the default, style.css adds dark-mode styling overrides, and the new SVG files are static dark-mode assets. There are no production application code, infrastructure, auth, permissions, data, or shared-library changes.
The latest update since the existing approval only standardizes CSS alpha formatting and expands a comment about a brittle Mintlify selector, so the risk level has not increased. I found no CODEOWNERS file in the PR head, and docs.json parses as valid JSON. The PR is already approved, so I’m not adding another approval.
Sent by Cursor Automation: Assign PR reviewers
2 participants
Summary
Enables the Mintlify theme toggle so docs readers can switch to dark mode, with all dark-mode values aligned to the Kernel brand system. Default appearance stays
light— first-time visitors see no change, the toggle is opt-in.Brand alignment
Every value introduced by this PR maps to a token in the Kernel design system:
#212225(kernelgrey-dark-03/charcoal)#EDEEF0(kernelgrey-dark-12) — used for body text, logo, and the tinker-bot illustration#CAB168(kernelgold) — kept unchanged across both modes, also used for the Warning callout iconrgba(237, 238, 240, …)— grey-dark-12 at low opacity (brand book lists white as "rare; prefer beige/grey-dark-12")WCAG AAA contrast on
#212225: body 13.7:1, gold 7.57:1, green 6.35:1.Proposed brand extension (flagging for design review)
The dark-mode subtle-surface tints (6 alpha steps:
0.02 / 0.03 / 0.04 / 0.08 / 0.10 / 0.14) form a "surface depth" scale used on table fills, borders, the tinker-box edge, and the Warning callout panel. These alphas are not on the brand book's defined opacity scale (0, 32, 64, 100) — but that scale was written for CSS opacity utility classes (likeopacity-32), not for alpha values insidergba()colors. Arguably a different concept.This PR ships the scale as a proposed extension to the brand system. Recommend ratifying it as named tokens (e.g.
--surface-overlay-01..05) inkernel/websiteso docs + dashboard can share the same scale.Changes
docs.json—appearance.strict: false, dark logo + dark background#212225.logo/white.svg—#EDEEF0recolor of the existing logo (paths identical toblack.svg) used in dark mode. Filename matches the brand book's "white monochrome" variant terminology.style.css—html.dark-scoped overrides for tables, the.tinker-boxborder, the pricing button border, and the Warning callout. Light mode rules untouched.images/tinker-bot-dark.svg+ one CSS swap — the hero bot is a flat#1C2024silhouette that disappears against the dark page bg, so it gets a#EDEEF0recolor viacontent: url(). Selector usessrc*=to handle the Mintlify CDN's image URL rewriting in production.Warning callout polish
Mintlify's default Warning renders as bright yellow on amber-brown — Eric flagged it as "harsh on the eyes." This PR brings the panel + border + icon in-line with the brand:
grey-dark-12alpha tints (matches table treatment)gold #CAB168(the brand's only approved warm accent)Note: the brand book reserves
goldfor "premium/enterprise" contexts. Using it on a Warning icon is a slight stretch of that intent. Gold is still being used as an accent (not a fill), which the brand rule explicitly allows.Inherited Mintlify defaults (unchanged in this PR)
The following are Mintlify default renderings, not introduced by this PR. They've been on prod for months (visible in light mode) and aren't managed by our
style.cssoverrides:A strict brand reading would override these to kernel tokens. We left them at the Mintlify default — same as light mode in prod, and keeps PR scope tight. Happy to push overrides if reviewers want strict treatment.
Notes
Test plan
/browsers/gpu-acceleration) no longer reads as "yellow on brown"Note
Low Risk
Documentation-only theming and static assets; no runtime APIs, auth, or data paths. Risk is mainly visual regressions if Mintlify changes callout class names.
Overview
Enables opt-in dark mode on the Mintlify docs by setting
appearance.stricttofalsewhile keepingdefault: light, so first-time visitors still see the current experience.Brand-aligned dark shell:
docs.jsonnow uses light/dark logos (black.svg/ newwhite.svg) and a dark page background#212225. Newimages/tinker-bot-dark.svgplus ahtml.darkCSS swap keeps the homepage hero bot visible on charcoal.Dark-only styling in
style.css: tables,.tinker-boxborders, pricing--btn-border, and yellow Warning callouts getgrey-dark-12alpha tints and gold icon color; light-mode rules are untouched.Reviewed by Cursor Bugbot for commit c2c2cb6. Bugbot is set up for automated code reviews on this repo. Configure here.