diff --git a/.github/workflows/docs-preview-fork.yml b/.github/workflows/docs-preview-fork.yml index 16ddfd6ab300..41f68811ba08 100644 --- a/.github/workflows/docs-preview-fork.yml +++ b/.github/workflows/docs-preview-fork.yml @@ -21,15 +21,18 @@ jobs: runs-on: ubuntu-latest steps: - name: Set pending commit status - uses: mattermost/actions/delivery/update-commit-status@fec7b836001c9380d4bfaf28d443945c103a098c env: - GITHUB_TOKEN: ${{ github.token }} - with: - repository_full_name: ${{ github.repository }} - commit_sha: ${{ inputs.COMMIT_SHA }} - context: docs-preview - description: "Docs preview build for ${{ inputs.COMMIT_SHA }} is running" - status: pending + COMMIT_SHA: ${{ inputs.COMMIT_SHA }} + CONTEXT_NAME: docs-preview + GH_TOKEN: ${{ github.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + GITHUB_RUN_ID: ${{ github.run_id }} + run: | + gh api "repos/${GITHUB_REPOSITORY}/statuses/${COMMIT_SHA}" \ + -f state=pending \ + -f context="${CONTEXT_NAME}" \ + -f description="Docs preview build for ${COMMIT_SHA} is running" \ + -f target_url="https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}" deploy: uses: ./.github/workflows/docs-preview-template.yml diff --git a/.github/workflows/docs-preview-template.yml b/.github/workflows/docs-preview-template.yml index 6033d5260458..fcf4b5e9730f 100644 --- a/.github/workflows/docs-preview-template.yml +++ b/.github/workflows/docs-preview-template.yml @@ -107,25 +107,30 @@ jobs: # Details (⋯) on this check links to the preview URL via target_url. - name: Set success commit status if: ${{ inputs.STATUS_CONTEXT != '' }} - uses: mattermost/actions/delivery/update-commit-status@fec7b836001c9380d4bfaf28d443945c103a098c env: - GITHUB_TOKEN: ${{ github.token }} - with: - repository_full_name: ${{ github.repository }} - commit_sha: ${{ inputs.COMMIT_SHA }} - context: ${{ inputs.STATUS_CONTEXT }} - description: "Docs preview build for ${{ inputs.COMMIT_SHA }} succeeded" - status: success - target_url: ${{ steps.preview.outputs.url }} + COMMIT_SHA: ${{ inputs.COMMIT_SHA }} + CONTEXT_NAME: ${{ inputs.STATUS_CONTEXT }} + PREVIEW_URL: ${{ steps.preview.outputs.url }} + GH_TOKEN: ${{ github.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + run: | + gh api "repos/${GITHUB_REPOSITORY}/statuses/${COMMIT_SHA}" \ + -f state=success \ + -f context="${CONTEXT_NAME}" \ + -f description="Docs preview build for ${COMMIT_SHA} succeeded" \ + -f target_url="$PREVIEW_URL" - name: Set failure commit status if: ${{ always() && inputs.STATUS_CONTEXT != '' && (failure() || cancelled()) }} - uses: mattermost/actions/delivery/update-commit-status@fec7b836001c9380d4bfaf28d443945c103a098c env: - GITHUB_TOKEN: ${{ github.token }} - with: - repository_full_name: ${{ github.repository }} - commit_sha: ${{ inputs.COMMIT_SHA }} - context: ${{ inputs.STATUS_CONTEXT }} - description: "Docs preview build for ${{ inputs.COMMIT_SHA }} failed" - status: failure + COMMIT_SHA: ${{ inputs.COMMIT_SHA }} + CONTEXT_NAME: ${{ inputs.STATUS_CONTEXT }} + GH_TOKEN: ${{ github.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + GITHUB_RUN_ID: ${{ github.run_id }} + run: | + gh api "repos/${GITHUB_REPOSITORY}/statuses/${COMMIT_SHA}" \ + -f state=failure \ + -f context="${CONTEXT_NAME}" \ + -f description="Docs preview build for ${COMMIT_SHA} failed" \ + -f target_url="https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}" diff --git a/docs/site/src/components/Callout/styles.module.css b/docs/site/src/components/Callout/styles.module.css index 9c97f0df5f4c..afaa48c883aa 100644 --- a/docs/site/src/components/Callout/styles.module.css +++ b/docs/site/src/components/Callout/styles.module.css @@ -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; } diff --git a/docs/site/src/css/custom.css b/docs/site/src/css/custom.css index 1748afe34c04..b9f7319536ed 100644 --- a/docs/site/src/css/custom.css +++ b/docs/site/src/css/custom.css @@ -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 `` (inside + * `
`) 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;
-}
-[data-theme='dark'] code {
-  background-color: var(--mm-denim-800);
-  border-color: var(--mm-denim-700);
+  /* 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;
+}
+/* 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,
diff --git a/docs/site/src/css/tokens.css b/docs/site/src/css/tokens.css
index 1d010e79c81d..e1b5fca05144 100644
--- a/docs/site/src/css/tokens.css
+++ b/docs/site/src/css/tokens.css
@@ -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);
 }