opensource/mattermost
3
0
Fork 0
mirror of https://github.com/mattermost/mattermost.git synced 2026-09-01 15:00:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

[Docs Revamp Feedback] Readability & accessibility fixes (#37665)

Browse Source 
* Fix readability & accessibility issues from Docs Revamp feedback

Addresses the readability/accessibility batch collected 2026-07-22/23 in
the "Docs Revamp - Feedback" channel and Eric Sethna's first-pass review
doc:

- Dark-mode "note" callout text vs. background contrast (Michael
  Roberson; Eric Sethna's doc item 8) — pin explicit brand colors for
  dark-mode admonitions instead of Infima's generic secondary-alert
  pairing.
- Link color/body-text visual distinction, both themes (Vishal
  Choudhary, Marco Kundt; Eric Sethna's doc item 5) — new link colors
  that stay far apart in luminance from surrounding body text (not just
  from the page background), plus default (not hover-only) underlines.
- Body text should read darker, like the old docs site (Vishal
  Choudhary) — wire --ifm-font-color-base to --mm-text-primary instead
  of Infima's unbranded default.
- Main content panel doesn't visually "pop" against the side nav/TOC
  (Vishal Choudhary) — tint the sidebar/TOC panels with --mm-bg-subtle
  and leave the reading column on the page background.
- Dark-mode inline code contrast (Marco Kundt) — explicit text color via
  --mm-text-primary.
- Bold/color combo hard to read (Ben Cooke) — subtle letter-spacing on
  bold runs in prose.
- Heading/TOC category font not readable, vs. the readable "IME" example
  (Eric Sethna's doc item 1) — swap the 900-weight display face out of
  small multi-word TOC category labels for the base sans face at bold
  weight, matching the same fix already applied to navbar links.
- Inline code spans taking up excess vertical space (Eric Sethna's doc
  item 9) — pin line-height on inline `code` so it stops inheriting the
  1.65 paragraph line-height; multi-line fences are unaffected.
- Prose max-width too wide on large screens (Rohith Chandran) — cap
  top-level article prose at ~760px via a `.markdown > `-scoped rule that
  leaves the OpenAPI 2-column layout (nested deeper) untouched.

Full WCAG contrast math for every changed pair is in the PR description.

Note: this touches docs/site/src/css/custom.css and tokens.css, which a
parallel "remove yellow left border" workstream also touches (callout/
card border styles) — left border/accent-bar colors are deliberately
untouched here to minimize overlap, but a merge conflict is still likely.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Address review feedback on readability/a11y PR

- Extend dark-mode admonition background fix from "note" to all five
  alert types (info/success/warning/danger) — the "hard on the eyes"
  complaint (item 13) wasn't note-specific. Also pin the alert heading
  label and icon color explicitly, since Infima's inheritance made the
  "NOTE"-style label the most visibly low-contrast part of the callout.
- Drop the default underline on prose links; use medium weight (600) as
  the non-color WCAG 1.4.1 cue instead, keeping underline for hover/focus
  only.
- Stop forcing code blocks to our --mm-denim-800 background in dark mode.
  Docusaurus's dark Prism theme (dracula) has its own background/token
  contrast pairing; overriding just the background broke that pairing.
  Letting the theme's own background show through (already applied to
  the block's container via --prism-background-color) fixes contrast.
- Apply the same small/multi-word-heading fix already used for TOC
  category labels to table column headers, which have the identical
  problem (multi-word labels in the 900-weight display face). Left
  footer titles on the heading face since those are short single words,
  the case that face handles fine — documented why.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix dark-mode contrast for code blocks, inline code, and note callouts

Code block, callout, and inline-code backgrounds/borders all sat within
~1:1 contrast of the dark-mode page background (same navy hue family),
so they had no visible edge or fill distinct from the page. The
unscoped dark-mode `code` background rule also leaked into code
blocks' own `<code>` element (beating Infima's `pre code: transparent`
on specificity), masking most of the code block fill behind a
near-black overlay regardless of the fill color chosen.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix dark-mode contrast for blockquotes, inline code, and table stripes

Same root cause as the earlier code-block/callout fixes: --mm-denim-800
and --mm-denim-700 sit within ~1:1 contrast of the dark-mode page
background, so blockquotes, inline code chips, and even-row table
striping all had no visible fill against the page. Switched them to
--mm-bg-surface (+ denim-400 borders where a border exists) to match
the surface treatment already used elsewhere.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Tone down h1 title weight; revert prose max-width cap

- h1 page titles were still on the 900-weight Archivo Black poster
  face after h2-h4 got moved to a normal-weight sans face for the
  same "too heavy/shouty" reason. Bring h1 in line with the rest so
  every page title uses one consistent weight.
- Revert the 760px max-width cap on top-level markdown prose blocks
  (added for Rohith Chandran's wide-line-length feedback) — it also
  squeezed non-article layouts like the homepage's persona cards.
  Needs more thought before reapplying narrower/more targeted.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Trim verbose CSS comments introduced in this branch

Cut reviewer-name/item-number attributions and repeated exploratory
narrative down to the "why" a future reader actually needs, and fixed
a couple of comments left stale by later commits (e.g. h1 no longer
using the Archivo Black display face). Also dropped a redundant
background declaration in the dark-mode .callout override that just
re-set the same value the base rule's --mm-bg-surface already
resolves to per theme.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Eva Sarafianou
2026-07-27 09:58:43 +03:00
committed by GitHub
parent 10b780cb09
commit f0de1f485b
3 changed files with 201 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/site/src/components/Callout/styles.module.css
+11 -1
View File
@@ -13,8 +13,13 @@
box-shadow: 0 1px 2px rgba(30, 50, 92, 0.04);
}
/* The base rule's --mm-border-subtle resolves to denim-700 in dark mode —
* ~1:1 contrast from the page background (#0E1525), so the box had no
* visible edge. --mm-border-strong (denim-500) is a real step up. Fill
* needs no override: --mm-bg-surface above already resolves to a
* theme-appropriate value per mode. */
[data-theme='dark'] .callout {
background: var(--mm-denim-800);
border-color: var(--mm-border-strong);
}
.bar {
@@ -61,6 +66,11 @@
/* Kind variants */
.note .bar { background: var(--mm-color-denim); }
.note .label { color: var(--mm-denim-600); }
/* Every other kind below pairs its light-mode label color with a
* dark-mode override — "note" was missing one, so it fell back to this
* light-mode-only denim-600 in dark mode too: dark navy text on a dark
* navy background. */
[data-theme='dark'] .note .label { color: var(--mm-denim-200); }
.tip .bar { background: #2C7A4F; } /* operational green */
.tip .label { color: #1F5A39; }
docs/site/src/css/custom.css
+174 -37
View File
@@ -19,8 +19,8 @@
--ifm-font-family-base: var(--mm-font-sans);
--ifm-font-family-monospace: var(--mm-font-mono);
--ifm-heading-font-family: var(--mm-font-heading);
--ifm-heading-font-weight: 900;
--ifm-heading-font-family: var(--mm-font-sans);
--ifm-heading-font-weight: 700;
--ifm-h1-font-size: 2.6rem;
--ifm-h2-font-size: 1.85rem;
--ifm-h3-font-size: 1.35rem;
@@ -49,11 +49,23 @@
--ifm-toc-border-color: var(--mm-border-subtle);
--ifm-hr-border-color: var(--mm-border-subtle);
/* Infima's own default body color isn't derived from our brand palette
* at all — pin it to --mm-text-primary for a guaranteed, auditable
* near-black. */
--ifm-font-color-base: var(--mm-text-primary);
--ifm-color-content: var(--mm-text-primary);
--ifm-font-color-secondary: var(--mm-text-secondary);
--ifm-color-content-secondary: var(--mm-text-secondary);
/* Sidebar */
--ifm-menu-color: var(--mm-denim-700);
--ifm-menu-color-active: var(--mm-color-denim);
--ifm-menu-color-background-active: var(--mm-denim-50);
--ifm-menu-color-background-hover: var(--mm-denim-50);
/* denim-100, not -50: the sidebar container itself now sits on
* --mm-bg-subtle (= denim-50, see .theme-doc-sidebar-container), so the
* active/hover highlight needs a visibly darker step or it'd disappear
* into its own background. */
--ifm-menu-color-background-active: var(--mm-denim-100);
--ifm-menu-color-background-hover: var(--mm-denim-100);
--ifm-menu-link-padding-vertical: 0.45rem;
--ifm-menu-link-padding-horizontal: 0.85rem;
}
@@ -79,6 +91,12 @@
--ifm-menu-color-active: var(--mm-color-white);
--ifm-menu-color-background-active: var(--mm-denim-700);
--ifm-menu-color-background-hover: var(--mm-denim-700);
/* See light-mode block above — same rationale, dark-mode near-white. */
--ifm-font-color-base: var(--mm-text-primary);
--ifm-color-content: var(--mm-text-primary);
--ifm-font-color-secondary: var(--mm-text-secondary);
--ifm-color-content-secondary: var(--mm-text-secondary);
}
/* === Type rhythm === */
@@ -98,19 +116,11 @@ body {
* apply a mild horizontal squeeze via font-stretch where the platform
* supports it (no-op on Archivo Black, which is fixed-width).
*
* The heavy display face is reserved for h1 page titles. h2-h4 are
* in-body section headers, not hero copy, so they use the regular
* sans family at a normal bold weight instead of the 900-weight
* poster face — otherwise every subheading reads as loud as the
* page title. */
h1 {
font-family: var(--mm-font-heading);
font-weight: 900;
letter-spacing: -0.025em;
line-height: 1.12;
font-stretch: 92%; /* ignored by static fonts; helps with variable Saira if loaded */
}
* h1 used to be 900-weight Archivo Black, but that read as too
* heavy/shouty for page titles at body-copy reading distance — same
* complaint that already moved h2-h4 to this sans-at-700 treatment, so
* h1 now shares it too (just at its own larger --ifm-h1-font-size). */
h1,
.markdown h2, .markdown h3, .markdown h4,
h2, h3, h4 {
font-family: var(--mm-font-sans);
@@ -119,6 +129,23 @@ h2, h3, h4 {
line-height: 1.25;
}
/* A touch of extra tracking on bold prose keeps adjacent heavy glyphs
* from visually merging — subtle enough not to loosen word shapes. */
.markdown strong,
.markdown b {
letter-spacing: 0.01em;
}
/* Color alone isn't a reliable "this is a link" signal (WCAG 1.4.1), but a
* default underline on every inline link reads as visual noise in body
* copy. Medium weight is the non-color cue instead — heavier than body
* text, without competing with `.markdown strong`'s bold weight or adding
* an underline (reserved for hover/focus). Scoped to prose so nav/footer/
* sidebar links keep their own treatments. */
.markdown a {
font-weight: 600;
}
/* Search results page ("See all results") — each hit's title is a plain h2
* outside `.markdown`, so it inherits the full --ifm-h2-font-size (1.85rem),
* as large as an in-article section header. Scoped to the wrapper class
@@ -255,7 +282,13 @@ h2, h3, h4 {
/* === Sidebar === */
/* Left nav, right TOC, and the main reading column previously all shared
* the same page background, so nothing set the article apart as "the
* content". Tinting just the side chrome with --mm-bg-subtle — leaving
* the main column on --mm-bg-page/-surface — makes the reading pane read
* as the brighter, foregrounded surface. */
.theme-doc-sidebar-container {
background-color: var(--mm-bg-subtle);
border-right: 1px solid var(--mm-border-subtle) !important;
}
[data-theme='dark'] .theme-doc-sidebar-container {
@@ -285,14 +318,19 @@ h2, h3, h4 {
}
/* Categories at any depth — including OpenAPI tag groups in the API
* sidebar (users → Users, audit logs → Audit Logs) — render in Trade
* Gothic Heavy with title case. (`::first-letter` doesn't apply to
* the menu link's flex layout, so we use text-transform: capitalize
* which capitalizes the first letter of every word.) */
* sidebar (users → Users, audit logs → Audit Logs) — render in title
* case. (`::first-letter` doesn't apply to the menu link's flex layout,
* so we use text-transform: capitalize which capitalizes the first
* letter of every word.)
*
* Font: Archivo Black's 900-weight display face reads fine for a short,
* single word/acronym at large size (e.g. an "IME" page title), but at
* this small size (0.82rem) its heavy strokes and tight kerning crowd
* multi-word labels together — use the body sans face at bold instead. */
.menu .menu__list-item-collapsible > .menu__link,
.menu > .menu__list > .menu__list-item > .menu__link {
font-family: var(--mm-font-heading);
font-weight: 900;
font-family: var(--mm-font-sans);
font-weight: 700;
letter-spacing: 0.02em;
text-transform: capitalize;
font-size: 0.82rem;
@@ -313,16 +351,79 @@ h2, h3, h4 {
/* === Code === */
code {
/* `:not(pre) > code`, not bare `code`: a code block's own `<code>` (inside
* `<pre>`) is also just a `code` element, and this rule's specificity
* ([data-theme='dark'] + tag) beats Infima's `pre code { background:
* transparent }` (two tags only). Left unscoped, this inline-code
* background painted over almost the entire visible area of every
* dark-mode code block. */
:not(pre) > code {
background-color: var(--mm-denim-50);
color: var(--mm-text-primary);
border: 1px solid var(--mm-border-subtle);
border-radius: 3px;
padding: 0.1em 0.35em;
font-size: 0.88em;
/* Infima's `code` selector has no line-height of its own, so an inline
* code span inherits the paragraph's 1.65 --ifm-line-height-base,
* inflating the whole line's height wherever one shows up mid-sentence.
* Multi-line fences are unaffected — `pre code` has higher specificity
* and `.theme-code-block .prism-code` sets its own line-height. */
line-height: 1.2;
}
[data-theme='dark'] code {
background-color: var(--mm-denim-800);
border-color: var(--mm-denim-700);
/* Same dark-on-dark collision as blockquote/callout/code-block: denim-800
* (#0C1424) and denim-700 (#121E37) are both within ~1:1 contrast of the
* page background (#0E1525), so inline code like `ClusterEncryptionKey`
* had no visible chip around it in dark mode. --mm-bg-surface + denim-400
* match the fill/border already used for code blocks elsewhere in this
* file, for a consistent "raised surface" look across all code UI. */
[data-theme='dark'] :not(pre) > code {
background-color: var(--mm-bg-surface);
border-color: var(--mm-denim-400);
}
/* === Admonitions / callouts ===
* Dark-mode callout text/label/icon were nearly the same color as the
* background across all five admonition types (note/tip/info/warning/
* danger) — Infima's default alert coloring was never wired to our brand
* tokens. Pin explicit, contrast-checked colors instead. Left border/
* accent-bar colors (--ifm-alert-border-color) are intentionally left
* untouched — a parallel "remove yellow left border" workstream reworks
* those on the same selectors.
*
* Heading label and icon are set explicitly (not just via the shared
* --ifm-alert-foreground-color below) since the label was the most
* visibly low-contrast part, in case a theme upgrade changes the
* inheritance. */
[data-theme='dark'] .alert {
--ifm-alert-foreground-color: var(--mm-callout-text);
}
[data-theme='dark'] .alert__heading,
[data-theme='dark'] .alert__icon svg {
color: var(--mm-callout-text);
fill: var(--mm-callout-text);
}
/* denim-700 (the previous note/info background) is ~1.1:1 from the page
* — same navy hue family, no visible surface. success/warning/danger
* don't have this problem since green/amber/red are a different hue
* family from the page. Fix: denim-500 (brand primary, ~4x page
* luminance) as the fill, plus a border (separate from the reserved
* --ifm-alert-border-color/left accent bar) for a crisp edge. */
[data-theme='dark'] .alert--secondary,
[data-theme='dark'] .alert--info {
--ifm-alert-background-color: var(--mm-denim-500);
border-top: 1px solid var(--mm-denim-300);
border-right: 1px solid var(--mm-denim-300);
border-bottom: 1px solid var(--mm-denim-300);
}
[data-theme='dark'] .alert--success {
--ifm-alert-background-color: #14442c;
}
[data-theme='dark'] .alert--warning {
--ifm-alert-background-color: #4a3a10;
}
[data-theme='dark'] .alert--danger {
--ifm-alert-background-color: #4a1f1f;
}
.theme-code-block {
@@ -331,16 +432,35 @@ code {
box-shadow: none !important;
}
/* --mm-denim-700 (#121E37) is only ~1.1:1 contrast from the page
* background (#0E1525) — same dark-navy hue family, no visible edge.
* denim-400 is a real jump in lightness, giving the block a border that
* actually reads as a boundary. */
[data-theme='dark'] .theme-code-block {
border-color: var(--mm-denim-700);
border-color: var(--mm-denim-400);
}
/* Light mode uses the "github" Prism theme (near-white bg) — --mm-denim-50
* keeps it in the brand palette without breaking github's token contrast.
*
* Dark mode uses "dracula" (docusaurus.config.ts), whose token colors are
* tuned against its own #282a36 background — don't hardcode a different
* background here, or token colors go muddy/low-contrast. But dracula's own
* #282a36 is only ~1.3:1 from our page bg (#0E1525), i.e. visually the same,
* 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. */
.theme-code-block .prism-code {
font-size: 0.85rem;
background: var(--mm-denim-50) !important;
}
[data-theme='dark'] .theme-code-block .prism-code {
background: var(--mm-denim-800) !important;
background: #52607A !important;
}
/* Copy button — denim border, marigold on hover */
@@ -365,11 +485,14 @@ table {
table thead {
background: var(--mm-color-denim);
}
/* Same problem as the TOC category labels above — multi-word headers
* like "Feature category" at 0.78rem crowd together in Archivo Black.
* Same fix: base sans face at bold weight. */
table thead th {
color: var(--mm-color-white);
font-family: var(--mm-font-heading);
font-weight: 900;
letter-spacing: 0.04em;
font-family: var(--mm-font-sans);
font-weight: 700;
letter-spacing: 0.03em;
text-transform: uppercase;
font-size: 0.78rem;
padding: 0.85rem 1rem;
@@ -383,8 +506,10 @@ table tbody td {
table tbody tr:nth-child(even) {
background: var(--mm-denim-50);
}
/* Same collision as blockquote/callout/code — denim-800 zebra striping
* was indistinguishable from the page background in dark mode. */
[data-theme='dark'] table tbody tr:nth-child(even) {
background: var(--mm-denim-800);
background: var(--mm-bg-surface);
}
/* === Blockquote === */
@@ -397,6 +522,13 @@ blockquote {
border-radius: 0 4px 4px 0;
color: var(--mm-text-primary);
}
/* --mm-bg-subtle in dark mode is denim-800 (#0C1424), effectively the same
* as the page background — same collision already fixed for callouts and
* code blocks. The marigold left border already reads fine; only the
* fill needed the surface-level bump. */
[data-theme='dark'] blockquote {
background: var(--mm-bg-surface);
}
/* === Footer === */
@@ -410,6 +542,10 @@ blockquote {
color: var(--ifm-footer-color);
padding: 3.5rem 1rem 2.5rem;
}
/* Footer column titles ("Docs", "Community", "More") stay on the heading
* face: short, single words are the case Archivo Black handles fine —
* it's small multi-word labels (TOC categories, table headers above)
* that crowd together at this weight. */
.footer__title {
color: var(--ifm-footer-title-color);
font-family: var(--mm-font-heading);
@@ -430,8 +566,7 @@ blockquote {
/* Docusaurus's default `.theme-doc-markdown` is fluid; we don't constrain
* it. The OpenAPI plugin's 2-column layout (request panel on the right)
* needs the full width of the article column. Long-form prose pages get
* comfortable measure via the article container's natural max-width. */
* needs the full width of the article column. */
.theme-doc-markdown {
font-size: 1rem;
}
@@ -473,10 +608,12 @@ blockquote {
min-width: 0;
}
/* TOC right column (per-page) */
/* TOC right column (per-page) — same side-panel treatment as the left
* sidebar, see comment above `.theme-doc-sidebar-container`. */
.table-of-contents {
background-color: var(--mm-bg-subtle);
border-left: 1px solid var(--mm-border-subtle);
padding: 0.4rem 0 0.4rem 1rem;
padding: 0.4rem 0.75rem 0.4rem 1rem;
font-size: 0.82rem;
}
.table-of-contents__link--active,
docs/site/src/css/tokens.css
+16 -2
View File
@@ -61,7 +61,11 @@
--mm-text-on-accent: var(--mm-color-black); /* black text on marigold */
--mm-border-subtle: var(--mm-denim-100);
--mm-border-strong: var(--mm-denim-300);
--mm-link: var(--mm-color-denim);
/* Not --mm-color-denim (#1E325C): it clears WCAG AA against white
* (12.6:1) but sits only ~1.5:1 from --mm-text-primary, so links and
* body copy read as the same shade of "dark". This blue keeps 6.5:1+
* against the page while staying clearly apart from body text. */
--mm-link: #3D5D96;
--mm-link-hover: var(--mm-denim-700);
--mm-accent: var(--mm-color-marigold);
--mm-focus-ring: var(--mm-marigold-500);
@@ -79,7 +83,17 @@
--mm-text-on-accent: var(--mm-color-black);
--mm-border-subtle: var(--mm-denim-700);
--mm-border-strong: var(--mm-denim-500);
--mm-link: var(--mm-color-sky);
/* Not --mm-color-sky (#C5D2EC): passes AA against the page (~12:1),
* but sits only ~1.5:1 from white body text, so links disappear into
* surrounding copy. This blue keeps ~6.4:1 against the page while
* reading clearly darker than white body text. */
--mm-link: #5B9BF0;
--mm-link-hover: var(--mm-color-white);
--mm-accent: var(--mm-color-marigold);
/* Infima's default secondary-alert text/background pairing isn't wired
* to our palette — pin explicit, contrast-checked brand colors instead.
* Left border/accent-bar colors are deliberately left alone — a
* parallel "remove yellow left border" workstream touches those. */
--mm-callout-text: var(--mm-denim-50);
--mm-callout-note-bg: var(--mm-denim-700);
}