style: mute body copy, and let the standfirst lead

[coderdan]

Body text moves to text-fd-muted-foreground; the text immediately under the heading moves to the foreground colour. Same rule in light and dark.

What was actually happening

Fumadocs ships the exact inverse:

	Fumadocs default	Now
Body copy (.prose)	--color-fd-foreground at 90%	--color-fd-muted-foreground
Standfirst (DocsDescription, the <p> under the H1)	text-fd-muted-foreground	text-fd-foreground

So the lead line was the quietest text on the page and the body the loudest.

Only --tw-prose-body moves. Headings, links, bold, code, quotes and captions each have their own --tw-prose-* variable pointing at the foreground token, so they keep full contrast — and read as more distinct now that paragraph text has stepped back. Both sides reference theme tokens, so light and dark follow automatically with no per-mode override.

One thing worth knowing about

The obvious version of this change is a silent no-op. Fumadocs declares .prose in @layer utilities. Cascade layers beat both specificity and source order, so putting the override in this file's existing @layer components block compiles clean and does nothing — no warning, no error, and it looks correct in the source.

I only caught it by checking the compiled CSS:

fumadocs  pos= 22790  layer=utilities
ours      pos=  9176  layer=components     <- loses

The fix is to leave the rule unlayered, since unlayered declarations outrank every layer — no !important needed, which matters because this file already leans on !important for its other Fumadocs overrides. Re-checked after the fix, the shipped rule lands unlayered. There's a comment in global.css saying so, because the next person to tidy it into the @layer components block below will otherwise quietly revert it.

Also verified in the built HTML that tailwind-merge collapses the class conflict rather than emitting both classes and leaving it to source order — the description renders text-lg mb-0 text-fd-foreground, with the default muted class dropped.

Scope

Applies to both page routes (/[[...slug]] and /stack/[[...slug]]), so the v2 and legacy trees stay consistent.

Worth a look when you review the preview: callout body text inherits the prose colour and is now muted too (callout titles and icons keep their own --callout-color). That reads as consistent to me — a callout is body copy — but it's the one place the change reaches beyond ordinary paragraphs, so it's your call. Cards are unaffected; they set text-fd-card-foreground explicitly.

Build is green at 763 pages.

---

Note: this will sit at Internal links — Expected until #81 merges, since the workflow only exists on that branch and v2 doesn't have it yet. Same situation as #39.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
public-docs	Ready	Preview, Comment	Jul 29, 2026 2:25am

[coderdan]

Pushed 308f082. Callout body text is back to full contrast and the padding is doubled — but first, a correction to what I told you in this PR's description.

I was wrong that this PR muted the callouts. Fumadocs hard-codes text-fd-muted-foreground on CalloutDescription:

cn("text-fd-muted-foreground prose-no-margin empty:hidden", className)

That's set directly on the description div, so it overrides any inherited prose colour — and only .prose itself consumes --tw-prose-body (one occurrence in the whole stylesheet). Callout text has always been muted; the body-copy change didn't touch it. My note flagging it as a side effect came from a static scan that found no explicit colour rule for callouts, and I didn't check the component. You'd have been looking for a regression that wasn't there.

The fix you asked for is the same either way, so:

Body text → text-fd-foreground, matching the title (the container is text-fd-card-foreground, which resolves to the same value in both themes). A callout now reads as one block rather than a heading over greyed-out copy — and stands out against the surrounding muted body copy, which is rather the point of a callout.

Padding → doubled, p-3 ps-1 → p-6 ps-2. I kept ps proportionally small because the accent bar is the container's first child and sits near the edge; doubling it to match the rest would have pushed the bar away from the border.

Both required reaching the description, which Fumadocs' Callout doesn't expose, so getMDXComponents now composes CalloutContainer / CalloutTitle / CalloutDescription — its exported primitives — instead of the convenience wrapper. CalloutContainer still resolves the warn/tip aliases and picks the icon, so only the six-line wrapper is reimplemented.

A dead rule found on the way: global.css has had this since the theme work:

[data-callout] { border-radius: 2px !important; }

Fumadocs never emits data-callout, so it has been matching nothing. Our wrapper now sets the attribute, so the rule applies — no visual change, because that 2px was already coming from the [class*="rounded-xl"] rule above it, but it's a real hook now rather than a decoy.

Verified in the built HTML rather than trusting tailwind-merge:

container:    ... bg-fd-card text-sm text-fd-card-foreground shadow-md p-6 ps-2  data-callout="true"
description:  prose-no-margin empty:hidden text-fd-foreground

Both conflicting pairs collapsed (p-3 ps-1 and the muted class are gone), and no muted class survives anywhere in the callout subtree. Build green, types:check and biome clean.

[coderdan]

Pushed fc360ff. The sidebar's resting nav items are text-fd-muted-foreground:

// fumadocs-ui/dist/layouts/docs/sidebar.js
itemVariants = cva("relative flex flex-row items-center gap-2 rounded-lg p-2
                    text-start text-fd-muted-foreground …")

which is the same token Fumadocs already used for callout body text. So this lands the colour back where it started, and the net effect of the callout work is now just the doubled padding and the data-callout hook.

That also removed the reason for hand-composing CalloutContainer / CalloutTitle / CalloutDescription — reaching the description was the only thing Fumadocs' Callout couldn't do. It spreads unknown props onto the container, so the wrapper is back to four lines over the public component, with no copy of its alias resolution, icon selection or title rendering to drift out of step. Smaller diff than the previous commit, not larger.

Verified in the built HTML that the two now match, and that the padding survived:

container: … bg-fd-card text-sm text-fd-card-foreground shadow-md p-6 ps-2
body:      text-fd-muted-foreground prose-no-margin empty:hidden
sidebar:   … rounded-lg p-2 text-start text-fd-muted-foreground …

Worth flagging for when you look at the preview: callout body and page body copy are now the same colour, since #82 also moves --tw-prose-body to text-fd-muted-foreground. A callout is still set apart by its card background, border, accent bar and icon — but no longer by text weight. If it ends up reading flat, the middle option is the pre-#82 body colour, color-mix(in oklab, var(--color-fd-foreground) 90%, transparent), which sits between the two you've tried. Happy either way; just say.

Build green, types:check and biome clean.

[coderdan]

Pushed 818db45 — callout body is now the middle setting: the colour prose body copy had before this branch muted it.

[data-callout] .prose-no-margin {
  color: color-mix(in oklab, var(--color-fd-foreground) 90%, transparent);
}

Where the three land, for the record:

	Value (dark)	Read
text-fd-foreground	hsl(42 18% 92%)	shouting
text-fd-muted-foreground (sidebar)	hsl(42 8% 55%)	identical to surrounding body copy
this	foreground @ 90%	a step above the page copy, below the headings

Done in CSS rather than threading a class through the component. Fumadocs puts text-fd-muted-foreground directly on the description div, so inheritance from the container can't reach it — the element has to be selected either way, and doing it here keeps the wrapper in mdx-components.tsx at four lines over the public Callout, with none of its internals duplicated.

The selector leans on data-callout (ours, from that wrapper) and prose-no-margin (Fumadocs' marker on the description's prose block). Unlayered, for the same reason as the .prose rule above it — the utility class being overridden lives in @layer utilities, and layer order beats specificity.

Verified rather than assumed, since this is the third attempt at the same line:

built CSS   [data-callout] .prose-no-margin{color:#0a0a0ae6}            <- srgb fallback
            @supports (color-mix) { … color-mix(in oklab,var(--color-fd-foreground)90%,transparent) }
            enclosing layers: UNLAYERED

built HTML  container   … shadow-md p-6 ps-2  data-callout="true"
            description text-fd-muted-foreground prose-no-margin empty:hidden   <- selector matches

Padding is untouched at p-6 ps-2. Build green, biome clean.