feat(design): align docs design system with mergify.com + dashboard by jd · Pull Request #11335 · Mergifyio/docs

jd · 2026-04-30T09:34:10Z

Establishes a three-layer CSS token system, drops three legacy
primitive systems, and adds typography utility classes documented in
a new DESIGN.md at the repo root.

The docs site had drifted away from the rest of Mergify's design
system: hex literals for section accents that happened to match the
canonical product palette by coincidence rather than by token, three
parallel color systems in theme.css (HSLA --color-base-, hex
--color-mergify-, --chakra-colors-*), no typography utilities, and
no DESIGN.md. New customers arriving from mergify.com saw a different
visual language. This change makes the docs site read as part of the
same product family.

Token system

src/styles/tokens.css (new) defines the primitive layer: a clean
gray ramp (gray-50..900, no duplicates) and the product palette
verbatim from mergify.com (teal/purple/orange/blue/coral/rose at
400 and 700, plus blue-800 for link hover).
src/styles/theme.css now has only the semantic layer
(--theme-text, --theme-bg, --theme-link, etc.), with light and
dark blocks each remapping the same set of names. Components
consume only the semantic layer.
The Chakra block, the --color-mergify-blue* family, and the HSLA
--color-base-* / lightness-suffix --color-{gray,blue,green,...}
ramps are gone. Legacy --theme-text-light / --theme-text-lighter
aliases are gone too.

Typography

src/styles/typography.css (new) defines utility classes
heading-hero / heading-page / heading-section / heading-subsection
/ heading-detail / heading-minor / text-subtitle / text-eyebrow.
MDX content auto-applies the same property set via the
#main-content h1..h6 rules in index.css.
The homepage migrates to utility classes (heading-hero,
text-subtitle, heading-section).

Section accents

The per-section ToC and sidebar styling block (~150 lines of
per-product duplication in index.css) collapses to a single
tokenized rule consuming var(--section-accent) and
var(--section-accent-bg). Each body.section-* class sets the two
custom properties from the product palette.
AcademyCallout, the merge-queue stat cards, and the changelog page
now reference product palette tokens directly since they are
intrinsically about a specific product.

Consumer migrations (Chakra → semantic, mergify-blue → semantic)

30+ files migrated across components/, pages/, styles/, and
astro.config.ts. Notable refactors:
- Button.astro: SCSS Chakra-ramp interpolation replaced with an
  explicit blue scheme. The other product/Chakra schemes were
  dead code (only colorScheme="blue" had callers) so they were
  dropped. Remaining hex literals in primary/secondary blocks are
  out of scope for this pass.
- Aside.astro: dynamic HSLA color computation replaced with
  explicit product palette tokens per callout type (note=blue,
  tip=teal, caution=orange, danger=coral).
- api-reference.css: response-code badges (2xx/3xx/4xx/5xx)
  migrated to color-mix() with product palette. Method badges
  keep their pre-existing hex literals (no clean palette mapping).
- Search.scss: hex search-highlight mark color replaced with
  var(--theme-link), already mode-aware.
Inline code drops the magenta accent — neutral text on a tinted
background distinguishes inline code via mono font + tint alone.

Documentation and tooling

DESIGN.md at the repo root documents the full system: token
vocabulary, product accents, dark mode mechanism, typography
utilities, voice (informational + on-voice for docs prose,
contrasted with marketing's "fun + arrogant"), and a STRICT code
rules section that future agents must follow.
AGENTS.md and CLAUDE.md gained a Design System section pointing
at DESIGN.md as the source of truth.
HeadCommon.astro loads the new CSS files in the correct cascade
order (tokens → theme → typography → index).
eslint.config.js scopes the MDX remark plugin to **/*.mdx only,
preventing remark-lint from running on root-level *.md files like
DESIGN.md and AGENTS.md.

Visual diff is small in light mode (1-2 hex points on neutrals) and
near-zero in dark mode. The docs reading experience is unchanged.

jd · 2026-04-30T09:34:13Z

This pull request is part of a Mergify stack:

#	Pull Request	Link
1	feat(design): align docs design system with mergify.com + dashboard	#11335	👈
2	fix(layout): redesign navbar for light-mode readability	#11336

mergify · 2026-04-30T09:35:13Z

Copilot

Pull request overview

Aligns the docs site styling with Mergify’s broader design system by introducing a layered token model (primitive → semantic → section accents), standardizing typography utilities, and migrating consumers off legacy Chakra/HSLA/mergify-blue variables.

Changes:

Added new primitive token and typography utility CSS, and updated global CSS load order to establish a predictable cascade.
Refactored theme.css to a semantic-only token layer (with dark-mode remaps) and migrated many components/pages to semantic tokens.
Introduced DESIGN.md (+ agent docs pointers) and adjusted ESLint MDX scoping to avoid linting root *.md.

Reviewed changes

Copilot reviewed 45 out of 45 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/styles/typography.css	Adds heading/typography utility classes for custom pages.
src/styles/tokens.css	Introduces primitive color tokens (neutral ramp + product palette).
src/styles/theme.css	Rebuilds theme into semantic tokens with a dedicated dark-mode remap block.
src/styles/index.css	Migrates globals to semantic tokens; adds tokenized section-accent system; syncs MDX heading styles.
src/styles/api-reference.css	Migrates API reference styling to semantic tokens + product palette via `color-mix()`.
src/pages/changelog/index.astro	Migrates changelog page styling off Chakra variables; tokenizes pills/tags.
src/pages/changelog/[slug].astro	Migrates changelog entry page styling to semantic tokens.
src/pages/404.astro	Migrates 404 page colors to semantic tokens.
src/content/docs/merge-queue.mdx	Updates inline styles to new palette/semantic tokens.
src/content/docs/index.mdx	Updates homepage MDX to typography utilities (`heading-`, `text-`).
src/components/Search/SearchBar.tsx	Migrates search UI text colors to semantic tokens.
src/components/Search/Search.scss	Tokenizes highlight and active-row styling; removes redundant dark override.
src/components/Search/Search.astro	Migrates search button styling to divider/muted semantic tokens.
src/components/Search/Results.tsx	Migrates results text colors to semantic tokens.
src/components/ScrollToTop.astro	Migrates scroll-to-top button colors/focus styles to semantic tokens.
src/components/RightSidebar/TableOfContents.css	Migrates ToC toggle icon colors to semantic tokens.
src/components/PageMeta.astro	Migrates PageMeta colors/hover link to semantic tokens.
src/components/PageFeedback.astro	Migrates PageFeedback colors/focus/selected state to semantic tokens.
src/components/PageContent/PageContent.astro	Migrates divider/scope colors to semantic tokens.
src/components/Modal/Modal.css	Migrates modal close color to semantic token.
src/components/MergeQueueCalculator/Stat.tsx	Migrates calculator text/indicator defaults to semantic tokens.
src/components/MergeQueueCalculator/SliderInput.tsx	Migrates slider label value color to semantic token.
src/components/MergeQueueCalculator/MergeQueueCalculator.tsx	Updates calculator container border token usage.
src/components/MergeQueueCalculator/MergeQueueCalculator.scss	Migrates calculator input/stepper styling tokens.
src/components/MergeQueueCalculator/LogSliderInput.tsx	Migrates log slider value color to semantic token.
src/components/LeftSidebar/NavLink.astro	Migrates sidebar icon/link colors to semantic tokens.
src/components/LeftSidebar/NavGroup.astro	Migrates sidebar icon color and dark active-link color to tokens.
src/components/Header/ThemeToggleButton.css	Migrates toggle checked state color to semantic tokens.
src/components/Header/SidebarToggle.css	Migrates mobile toggle base color to semantic divider token.
src/components/Header/HeaderLink.astro	Migrates header link/button text color to semantic token.
src/components/Header/HeaderButton.css	Migrates header button CSS vars to semantic tokens.
src/components/HeadCommon.astro	Ensures CSS is imported in the intended cascade order (tokens → theme → typography → index).
src/components/Footer/Footer.astro	Migrates footer link color to semantic token.
src/components/DocsetGrid/Docset.astro	Migrates docset card border to semantic border token.
src/components/CopyForLLMButton.astro	Migrates toolbar button styling to semantic tokens.
src/components/CommunityButton.astro	Migrates hover background to semantic offset surface token.
src/components/Button.astro	Drops unused Chakra colorScheme support; adds explicit blue scheme styling.
src/components/Breadcrumbs.astro	Migrates breadcrumb colors to semantic tokens.
src/components/Badge/Badge.css	Migrates badge background/text to product palette tokens via `color-mix()`.
src/components/Aside.astro	Replaces HSLA-derived callout colors with explicit palette token mapping per type.
src/components/AcademyCallout.astro	Migrates AcademyCallout accent styling to product palette tokens.
eslint.config.js	Restricts MDX linting to `*/.mdx` and adds `.claude/**` to ignores.
astro.config.ts	Updates style overrides to semantic tokens (border/link/focus/etc.).
DESIGN.md	Adds design-system documentation for tokens, typography, dark mode, and rules.
AGENTS.md	Adds a design-system pointer and summarizes key styling rules.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Establishes a three-layer CSS token system, drops three legacy primitive systems, and adds typography utility classes documented in a new DESIGN.md at the repo root. The docs site had drifted away from the rest of Mergify's design system: hex literals for section accents that happened to match the canonical product palette by coincidence rather than by token, three parallel color systems in theme.css (HSLA --color-base-*, hex --color-mergify-*, --chakra-colors-*), no typography utilities, and no DESIGN.md. New customers arriving from mergify.com saw a different visual language. This change makes the docs site read as part of the same product family. Token system - src/styles/tokens.css (new) defines the primitive layer: a clean gray ramp (gray-50..900, no duplicates) and the product palette verbatim from mergify.com (teal/purple/orange/blue/coral/rose at 400 and 700, plus blue-800 for link hover). - src/styles/theme.css now has only the semantic layer (--theme-text, --theme-bg, --theme-link, etc.), with light and dark blocks each remapping the same set of names. Components consume only the semantic layer. - The Chakra block, the --color-mergify-blue* family, and the HSLA --color-base-* / lightness-suffix --color-{gray,blue,green,...} ramps are gone. Legacy --theme-text-light / --theme-text-lighter aliases are gone too. Typography - src/styles/typography.css (new) defines utility classes heading-hero / heading-page / heading-section / heading-subsection / heading-detail / heading-minor / text-subtitle / text-eyebrow. - MDX content auto-applies the same property set via the #main-content h1..h6 rules in index.css. - The homepage migrates to utility classes (heading-hero, text-subtitle, heading-section). Section accents - The per-section ToC and sidebar styling block (~150 lines of per-product duplication in index.css) collapses to a single tokenized rule consuming var(--section-accent) and var(--section-accent-bg). Each body.section-* class sets the two custom properties from the product palette. - AcademyCallout, the merge-queue stat cards, and the changelog page now reference product palette tokens directly since they are intrinsically about a specific product. Consumer migrations (Chakra → semantic, mergify-blue → semantic) - 30+ files migrated across components/, pages/, styles/, and astro.config.ts. Notable refactors: - Button.astro: SCSS Chakra-ramp interpolation replaced with an explicit blue scheme. The other product/Chakra schemes were dead code (only colorScheme="blue" had callers) so they were dropped. Remaining hex literals in primary/secondary blocks are out of scope for this pass. - Aside.astro: dynamic HSLA color computation replaced with explicit product palette tokens per callout type (note=blue, tip=teal, caution=orange, danger=coral). - api-reference.css: response-code badges (2xx/3xx/4xx/5xx) migrated to color-mix() with product palette. Method badges keep their pre-existing hex literals (no clean palette mapping). - Search.scss: hex search-highlight mark color replaced with var(--theme-link), already mode-aware. - Inline code drops the magenta accent — neutral text on a tinted background distinguishes inline code via mono font + tint alone. Documentation and tooling - DESIGN.md at the repo root documents the full system: token vocabulary, product accents, dark mode mechanism, typography utilities, voice (informational + on-voice for docs prose, contrasted with marketing's "fun + arrogant"), and a STRICT code rules section that future agents must follow. - AGENTS.md and CLAUDE.md gained a Design System section pointing at DESIGN.md as the source of truth. - HeadCommon.astro loads the new CSS files in the correct cascade order (tokens → theme → typography → index). - eslint.config.js scopes the MDX remark plugin to **/*.mdx only, preventing remark-lint from running on root-level *.md files like DESIGN.md and AGENTS.md. Visual diff is small in light mode (1-2 hex points on neutrals) and near-zero in dark mode. The docs reading experience is unchanged. Change-Id: I6c7e207efdaca8e63f2254d7aaeb9e656c50e138

jd · 2026-04-30T12:07:10Z

Revision history

#	Type	Changes	Reason	Date
1	initial	`92a02fa`		2026-04-30 12:07 UTC
2	content	`92a02fa → 322d043`		2026-04-30 12:07 UTC

Pull request has been modified.

Copilot AI review requested due to automatic review settings April 30, 2026 09:34

mergify Bot had a problem deploying to Mergify Merge Protections April 30, 2026 09:34 Failure

jd mentioned this pull request Apr 30, 2026

fix(layout): redesign navbar for light-mode readability #11336

Open

Copilot started reviewing on behalf of jd April 30, 2026 09:34 View session

mergify Bot requested a review from a team April 30, 2026 09:36

sileht previously approved these changes Apr 30, 2026

View reviewed changes

mergify Bot requested a review from a team April 30, 2026 09:40

Copilot AI reviewed Apr 30, 2026

View reviewed changes

mergify Bot added the review threads unresolved label Apr 30, 2026

jd marked this pull request as ready for review April 30, 2026 11:52

jd force-pushed the devs/jd/worktree-design/align-docs-design-system-mergify-com-dashboard--6c7e207e branch from 92a02fa to 322d043 Compare April 30, 2026 12:07

mergify Bot had a problem deploying to Mergify Merge Protections April 30, 2026 12:07 Failure

mergify Bot removed the review threads unresolved label Apr 30, 2026

JulianMaurin approved these changes Apr 30, 2026

View reviewed changes

jd mentioned this pull request Apr 30, 2026

tmp: center sidebar logo + bump size #11345

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(design): align docs design system with mergify.com + dashboard#11335

feat(design): align docs design system with mergify.com + dashboard#11335
jd wants to merge 1 commit intomainfrom
devs/jd/worktree-design/align-docs-design-system-mergify-com-dashboard--6c7e207e

jd commented Apr 30, 2026

Uh oh!

jd commented Apr 30, 2026 •

edited

Loading

Uh oh!

mergify Bot commented Apr 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jd commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

Conversation

jd commented Apr 30, 2026

Uh oh!

jd commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mergify Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Protections

🔴 🤖 Continuous Integration

🔴 👀 Review Requirements

🟢 Enforce conventional commit

🟢 🔎 Reviews

🟢 📕 PR description

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jd commented Apr 30, 2026

Revision history

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

jd commented Apr 30, 2026 •

edited

Loading

mergify Bot commented Apr 30, 2026 •

edited

Loading