@karimsa/mdxserve 0.0.0-stage → 0.2.0

package/client/app.css

@@ -0,0 +1,372 @@
+/* mdxserve global stylesheet.
+ *
+ * Order matters:
+ *   1. @imports — tippy's base css (see the Tooltip note below), then the design
+ *      system's tokens and base styles (client/design/, ported verbatim from the
+ *      "mdxserve Design System" Claude Design project).
+ *   2. @custom-variant dark — the `dark:` utility variant keys on the
+ *      `data-theme` attribute that src/http/html.ts sets on <html>, not on the OS
+ *      media query, so the in-app toggle works.
+ *   3. @theme inline — exposes the design tokens to Tailwind so utilities like
+ *      `bg-surface-card` / `text-text-muted` / `shadow-sm` point straight at
+ *      the CSS variables (no duplicated values, dark mode comes for free).
+ *   4. App-specific rules that are not part of the design system proper.
+ *
+ * The design tokens are deliberately left *unlayered*: `@theme inline` entries
+ * whose name matches a token (`--font-mono`, `--radius-md`) emit a
+ * self-reference inside `@layer theme`, and the unlayered `:root` declaration
+ * is what wins the cascade. Wrapping client/design in @layer would break that.
+ */
+
+/* Base tippy.js styles for the builtin Tooltip component (client/builtins/Tooltip.tsx).
+   Imported here (rather than from the component) so it flows through Vite's normal
+   CSS pipeline and doesn't break scripts/build-registry.ts, which imports that
+   component under plain Node to read its zod schema. */
+@import "tippy.js/dist/tippy.css";
+
+@import "./design/tokens/fonts.css";
+@import "./design/tokens/colors.css";
+@import "./design/tokens/typography.css";
+@import "./design/tokens/spacing.css";
+@import "./design/tokens/elevation.css";
+@import "./design/tokens/motion.css";
+@import "./design/base/reset.css";
+@import "./design/base/prose.css";
+@import "./design/base/editor.css";
+
+/* `:root[...]` (not bare `[data-theme]`) because rehype-pretty-code stamps
+   data-theme="<shiki theme name>" on every <pre>/<code> it renders. */
+@custom-variant dark (&:where(:root[data-theme="dark"], :root[data-theme="dark"] *));
+
+@theme inline {
+	/* fonts */
+	--font-sans: var(--font-core);
+	--font-mono: var(--font-mono);
+
+	/* surfaces */
+	--color-surface-page: var(--surface-page);
+	--color-surface-card: var(--surface-card);
+	--color-surface-sunken: var(--surface-sunken);
+	--color-surface-raised: var(--surface-raised);
+	--color-surface-inverse: var(--surface-inverse);
+	--color-surface-hover: var(--surface-hover);
+	--color-surface-active: var(--surface-active);
+	--color-surface-accent-soft: var(--surface-accent-soft);
+	--color-surface-accent: var(--surface-accent);
+
+	/* text */
+	--color-text-body: var(--text-body);
+	--color-text-heading: var(--text-heading);
+	--color-text-muted: var(--text-muted);
+	--color-text-subtle: var(--text-subtle);
+	--color-text-inverse: var(--text-inverse);
+	--color-text-accent: var(--text-accent);
+	--color-text-link: var(--text-link);
+	--color-text-link-hover: var(--text-link-hover);
+
+	/* borders */
+	--color-border-subtle: var(--border-subtle);
+	--color-border-default: var(--border-default);
+	--color-border-strong: var(--border-strong);
+	--color-border-accent: var(--border-accent);
+	--color-focus-ring: var(--focus-ring);
+
+	/* status tints (callouts, badges, toasts) */
+	--color-status-info-bg: var(--status-info-bg);
+	--color-status-info-fg: var(--status-info-fg);
+	--color-status-ok-bg: var(--status-ok-bg);
+	--color-status-ok-fg: var(--status-ok-fg);
+	--color-status-warn-bg: var(--status-warn-bg);
+	--color-status-warn-fg: var(--status-warn-fg);
+	--color-status-danger-bg: var(--status-danger-bg);
+	--color-status-danger-fg: var(--status-danger-fg);
+	--color-status-note-bg: var(--status-note-bg);
+	--color-status-note-fg: var(--status-note-fg);
+
+	/* code surfaces */
+	--color-code-bg: var(--code-bg);
+	--color-code-bg-inline: var(--code-bg-inline);
+	--color-code-fg: var(--code-fg);
+	--color-code-border: var(--code-border);
+	--color-code-gutter: var(--code-gutter);
+	--color-code-highlight: var(--code-highlight);
+
+	/* raw ramps, for the few places the design names them directly */
+	--color-teal-50: var(--teal-50);
+	--color-teal-100: var(--teal-100);
+	--color-teal-200: var(--teal-200);
+	--color-teal-300: var(--teal-300);
+	--color-teal-400: var(--teal-400);
+	--color-teal-500: var(--teal-500);
+	--color-teal-550: var(--teal-550);
+	--color-teal-600: var(--teal-600);
+	--color-teal-700: var(--teal-700);
+	--color-teal-800: var(--teal-800);
+	--color-teal-900: var(--teal-900);
+	--color-n-0: var(--n-0);
+	--color-n-25: var(--n-25);
+	--color-n-50: var(--n-50);
+	--color-n-100: var(--n-100);
+	--color-n-200: var(--n-200);
+	--color-n-300: var(--n-300);
+	--color-n-400: var(--n-400);
+	--color-n-500: var(--n-500);
+	--color-n-600: var(--n-600);
+	--color-n-700: var(--n-700);
+	--color-n-800: var(--n-800);
+	--color-n-900: var(--n-900);
+	--color-n-950: var(--n-950);
+
+	/* shadows — the one namespace Tailwind would otherwise inline its own
+     literal values for, so these mappings are required, not cosmetic */
+	--shadow-xs: var(--shadow-xs);
+	--shadow-sm: var(--shadow-sm);
+	--shadow-md: var(--shadow-md);
+	--shadow-lg: var(--shadow-lg);
+	--shadow-hairline: var(--shadow-hairline);
+	--shadow-focus: var(--shadow-focus);
+
+	/* radii — token names already match Tailwind's; listed for the extras */
+	--radius-xs: var(--radius-xs);
+	--radius-sm: var(--radius-sm);
+	--radius-md: var(--radius-md);
+	--radius-lg: var(--radius-lg);
+	--radius-xl: var(--radius-xl);
+	--radius-pill: var(--radius-pill);
+
+	/* layout */
+	--spacing-sidebar: var(--sidebar-width);
+	--spacing-toc: var(--toc-width);
+	--spacing-topbar: var(--topbar-height);
+	--container-prose: var(--width-prose);
+	--container-content: var(--width-content);
+
+	/* motion */
+	--ease-standard: var(--ease-standard);
+	--ease-out: var(--ease-out);
+	--ease-in: var(--ease-in);
+}
+
+/* Opt out of the global focus ring for inputs whose container already shows
+   focus (the search palette's text field). */
+[data-bare-focus]:focus-visible {
+	box-shadow: none;
+}
+
+/* Anchor jumps (TOC, `.mdx-anchor`, in-page links) clear the sticky topbar and
+   glide rather than snap. Programmatic scrolls that should not animate (route
+   change reset, first-load hash) pass `behavior: "instant"` explicitly. */
+html {
+	scroll-padding-top: calc(var(--topbar-height) + var(--space-2));
+}
+
+@media (prefers-reduced-motion: no-preference) {
+	html {
+		scroll-behavior: smooth;
+	}
+}
+
+.mdx-prose h1,
+.mdx-prose h2,
+.mdx-prose h3,
+.mdx-prose h4 {
+	scroll-margin-top: calc(var(--topbar-height) + var(--space-2));
+}
+
+/* Tailwind preflight resets list-style; the design's prose.css assumes markers. */
+.mdx-prose ul:not(:where(.not-prose, .not-prose *)) {
+	list-style: disc;
+}
+
+.mdx-prose ol:not(:where(.not-prose, .not-prose *)) {
+	list-style: decimal;
+}
+
+.mdx-prose ul ul:not(:where(.not-prose, .not-prose *)) {
+	list-style: circle;
+}
+
+/* GFM task list items: the checkbox is the marker. */
+.mdx-prose li:has(> input[type="checkbox"]) {
+	list-style: none;
+	margin-left: -1.35em;
+}
+
+.mdx-prose li > input[type="checkbox"] {
+	margin: 0 0.5em 0 0;
+	accent-color: var(--teal-550);
+	vertical-align: -0.1em;
+}
+
+/* `not-prose` is a marker class (it used to come from @tailwindcss/typography).
+   Every element rule in client/design/base/prose.css carries a
+   `:not(:where(.not-prose, .not-prose *))` guard, so a builtin that sets it on
+   its root keeps its own typography. No rule is needed for the class itself. */
+
+/* Code blocks: hand off entirely to CodeFrame/Pre (client/CodeBlock.tsx) — prose
+   must not impose padding, background, or figcaption styling on them. Scoped to
+   rehype-pretty-code's figure so component <figure>s (Chart, Diagram) keep their
+   own radius and the prose block gap. The `.mdx-prose code` inline chip rule must
+   not hit code inside a <pre> either. */
+.mdx-prose pre,
+.mdx-prose pre code,
+.mdx-prose figure[data-rehype-pretty-code-figure] {
+	margin: 0;
+	padding: 0;
+	background: transparent;
+	font: var(--type-code);
+	color: var(--code-fg);
+	border-radius: 0;
+}
+
+/* Same `:is()` widening as prose.css's direct-child rhythm rules — a code
+   block can sit inside a `.mdx-section` wrapper or a section's own edit-mode
+   `.ProseMirror` surface, not just bare under `.mdx-prose`. */
+:is(.mdx-prose, .mdx-section, .mdx-prose .ProseMirror) > figure[data-rehype-pretty-code-figure] + *,
+:is(.mdx-prose, .mdx-section, .mdx-prose .ProseMirror)
+	> *
+	+ figure[data-rehype-pretty-code-figure] {
+	margin-top: var(--prose-gap);
+}
+
+/* Padding lives here (not in utility classes) so the unlayered reset above
+   can't strip it; CodeFrame's <pre> relies on it. */
+.mdx-prose pre,
+.not-prose pre {
+	padding: var(--space-4) 0;
+}
+
+/*
+ * rehype-pretty-code line rendering (client/CodeBlock.tsx owns the surrounding
+ * card; this handles the per-line grid rows it emits):
+ *   - every line is a `<span data-line>` inside a `<code style="display:grid">`,
+ *     so it stretches to the full (possibly scrolled) width by default.
+ *   - `showLineNumbers` meta sets `data-line-numbers` on `<code>` and
+ *     `data-line-numbers-max-digits` to the gutter's digit count.
+ *   - `{1,3-4}`-style meta sets `data-highlighted-line` on the matching lines.
+ */
+[data-line] {
+	padding-inline: var(--space-4);
+}
+
+[data-highlighted-line] {
+	background-color: var(--code-highlight);
+	box-shadow: inset 2px 0 0 var(--teal-400);
+}
+
+code[data-line-numbers] {
+	counter-reset: line;
+}
+
+code[data-line-numbers] [data-line]::before {
+	counter-increment: line;
+	content: counter(line);
+	display: inline-block;
+	width: 1ch;
+	margin-right: var(--space-4);
+	text-align: right;
+	color: var(--code-gutter);
+	user-select: none;
+}
+
+code[data-line-numbers-max-digits="2"] [data-line]::before {
+	width: 2ch;
+}
+
+code[data-line-numbers-max-digits="3"] [data-line]::before {
+	width: 3ch;
+}
+
+code[data-line-numbers-max-digits="4"] [data-line]::before {
+	width: 4ch;
+}
+
+/* Tippy theme for the builtin Tooltip component (client/builtins/Tooltip.tsx).
+   The arrow's border-*-color is `initial` (== currentcolor) per placement in
+   tippy.js/dist/tippy.css, picking up whatever `color` is set on the arrow
+   element itself — so setting `color` on `::before` (not just `.tippy-arrow`)
+   is what actually tints it. Inverse surface in both themes. */
+.tippy-box[data-theme~="mdxserve"] {
+	background: var(--surface-inverse);
+	color: var(--text-inverse);
+	font: var(--type-ui-sm);
+	font-size: var(--size-xs);
+	border-radius: var(--radius-md);
+	padding: var(--space-0-5) var(--space-1);
+	box-shadow: var(--shadow-md);
+}
+
+.tippy-box[data-theme~="mdxserve"] > .tippy-arrow::before {
+	color: var(--surface-inverse);
+}
+
+/* Folder listing titles are rendered from the doc's first h1 as inline HTML. */
+/* Keep this in lockstep with the `.mdx-prose code` chip in design/base/prose.css. */
+.listing-title code {
+	font: var(--type-code-inline);
+	background: var(--code-bg-inline);
+	color: var(--text-accent);
+	padding: 0.12em 0.34em;
+	border-radius: var(--radius-xs);
+}
+
+/* Wide tables scroll within the prose column instead of overflowing it. The
+   wrapper takes the table's block margin so the prose gap is unchanged. */
+.mdx-table-scroll {
+	max-width: 100%;
+	overflow-x: auto;
+}
+.mdx-table-scroll > table {
+	margin-bottom: 0;
+}
+
+/* client/ui/Toast.tsx's attention bounce for a repeat push. Two keyframe sets
+   with identical frames: CSS only restarts an animation when its
+   animation-name changes, so a repeat push flips the wrapper between the two
+   names to replay the bounce. */
+@keyframes toast-bump-a {
+	0% {
+		transform: none;
+	}
+	40% {
+		transform: translateY(-6px) scale(1.03);
+	}
+	100% {
+		transform: none;
+	}
+}
+@keyframes toast-bump-b {
+	0% {
+		transform: none;
+	}
+	40% {
+		transform: translateY(-6px) scale(1.03);
+	}
+	100% {
+		transform: none;
+	}
+}
+.toast-bump-a {
+	animation: toast-bump-a 380ms cubic-bezier(0.2, 0, 0.2, 1);
+}
+.toast-bump-b {
+	animation: toast-bump-b 380ms cubic-bezier(0.2, 0, 0.2, 1);
+}
+/* The ×N chip already says a repeat landed; the bounce is decoration. */
+@media (prefers-reduced-motion: reduce) {
+	.toast-bump-a,
+	.toast-bump-b {
+		animation: none;
+	}
+}
+
+/* Print: the reader gets the prose, nothing else. */
+@media print {
+	[data-print-hide] {
+		display: none !important;
+	}
+
+	.mdx-anchor {
+		display: none;
+	}
+}

package/client/builtins/Badge.tsx

@@ -0,0 +1,109 @@
+import type { ReactNode } from "react";
+import { z } from "zod";
+
+export const badgeProps = z.object({
+	tone: z
+		.enum(["neutral", "teal", "info", "ok", "warn", "danger", "note"])
+		.default("neutral")
+		.describe("Tone of the badge."),
+	color: z
+		.enum(["gray", "sky", "green", "amber", "red", "violet"])
+		.optional()
+		.describe(
+			"Deprecated alias for `tone` (gray→neutral, sky→info, green→ok, amber→warn, red→danger, violet→note). Prefer `tone`.",
+		),
+	variant: z.enum(["soft", "solid", "outline"]).default("soft").describe("Fill style."),
+	dot: z.boolean().default(false).describe("Show a leading status dot."),
+	children: z.custom<ReactNode>().describe("Badge label."),
+});
+
+export type BadgeProps = z.infer<typeof badgeProps>;
+
+type Tone = NonNullable<BadgeProps["tone"]>;
+type Variant = NonNullable<BadgeProps["variant"]>;
+
+const COLOR_TO_TONE: Record<NonNullable<BadgeProps["color"]>, Tone> = {
+	gray: "neutral",
+	sky: "info",
+	green: "ok",
+	amber: "warn",
+	red: "danger",
+	violet: "note",
+};
+
+function resolveTone({ tone, color }: Pick<BadgeProps, "tone" | "color">): Tone {
+	if (tone) return tone;
+	if (color) return COLOR_TO_TONE[color];
+	return "neutral";
+}
+
+const TONE_STYLES: Record<Tone, Record<Variant, string>> = {
+	neutral: {
+		soft: "bg-surface-sunken text-text-muted border-border-default",
+		solid: "bg-n-600 text-n-0 border-transparent",
+		outline: "bg-transparent text-text-muted border-border-default",
+	},
+	teal: {
+		soft: "bg-surface-accent-soft text-text-accent border-teal-200",
+		solid: "bg-teal-550 text-n-0 border-transparent",
+		outline: "bg-transparent text-text-accent border-teal-300",
+	},
+	info: {
+		soft: "bg-status-info-bg text-status-info-fg border-transparent",
+		solid: "bg-status-info-fg text-text-inverse border-transparent",
+		outline: "bg-transparent text-status-info-fg border-current",
+	},
+	ok: {
+		soft: "bg-status-ok-bg text-status-ok-fg border-transparent",
+		solid: "bg-status-ok-fg text-text-inverse border-transparent",
+		outline: "bg-transparent text-status-ok-fg border-current",
+	},
+	warn: {
+		soft: "bg-status-warn-bg text-status-warn-fg border-transparent",
+		solid: "bg-status-warn-fg text-text-inverse border-transparent",
+		outline: "bg-transparent text-status-warn-fg border-current",
+	},
+	danger: {
+		soft: "bg-status-danger-bg text-status-danger-fg border-transparent",
+		solid: "bg-status-danger-fg text-text-inverse border-transparent",
+		outline: "bg-transparent text-status-danger-fg border-current",
+	},
+	note: {
+		soft: "bg-status-note-bg text-status-note-fg border-transparent",
+		solid: "bg-status-note-fg text-text-inverse border-transparent",
+		outline: "bg-transparent text-status-note-fg border-current",
+	},
+};
+
+const DOT_STYLES: Record<Tone, string> = {
+	neutral: "bg-n-500",
+	teal: "bg-teal-500",
+	info: "bg-status-info-fg",
+	ok: "bg-status-ok-fg",
+	warn: "bg-status-warn-fg",
+	danger: "bg-status-danger-fg",
+	note: "bg-status-note-fg",
+};
+
+export default function Badge({
+	tone,
+	color,
+	variant = "soft",
+	dot = false,
+	children,
+}: BadgeProps) {
+	const resolved = resolveTone({ tone, color });
+	return (
+		<span
+			className={`not-prose inline-flex items-center gap-1.5 h-5 rounded-sm border px-1.5 font-sans leading-normal text-[length:var(--size-xs)] font-semibold ${TONE_STYLES[resolved][variant]}`}
+		>
+			{dot ? (
+				<span
+					className={`h-1.5 w-1.5 shrink-0 rounded-full ${DOT_STYLES[resolved]}`}
+					aria-hidden="true"
+				/>
+			) : null}
+			{children}
+		</span>
+	);
+}

package/client/builtins/Button.tsx

@@ -0,0 +1,111 @@
+import type { ReactNode } from "react";
+import { motion } from "framer-motion";
+import { z } from "zod";
+import { TRANSITIONS } from "../motion";
+import { Icon } from "../ui/Icon";
+
+export const buttonProps = z.object({
+	variant: z
+		.enum(["primary", "secondary", "ghost", "danger"])
+		.default("primary")
+		.describe(
+			"Visual style: primary (filled teal), secondary (outlined), ghost (text-only), or danger (outlined, danger tone).",
+		),
+	size: z.enum(["sm", "md", "lg"]).default("md").describe("Height/padding/text size."),
+	icon: z.string().optional().describe("Lucide icon name rendered before the label."),
+	iconRight: z.string().optional().describe("Lucide icon name rendered after the label."),
+	href: z
+		.string()
+		.optional()
+		.describe("If set, renders as a link (`<a>`) instead of a `<button>`."),
+	onClick: z.custom<() => void>().optional().describe("Click handler (MDX/JSX only)."),
+	disabled: z.boolean().default(false).describe("Disables the button and dims it."),
+	autoFocus: z.boolean().optional().describe("Focus the button on mount."),
+	children: z.custom<ReactNode>().describe("Button label/content."),
+});
+
+// z.input, not z.infer: fields with zod defaults stay optional for TSX callers
+// (the component destructures the same defaults itself).
+export type ButtonProps = z.input<typeof buttonProps>;
+
+type Variant = NonNullable<ButtonProps["variant"]>;
+type Size = NonNullable<ButtonProps["size"]>;
+
+const VARIANT_STYLES: Record<Variant, string> = {
+	primary: "bg-teal-550 text-n-0 border border-teal-600 shadow-xs hover:bg-teal-600",
+	secondary:
+		"bg-surface-card text-text-body border border-border-default shadow-xs hover:bg-surface-hover",
+	ghost: "bg-transparent text-text-muted border border-transparent hover:bg-surface-hover",
+	danger:
+		"bg-surface-card text-status-danger-fg border border-border-default hover:bg-status-danger-bg",
+};
+
+const SIZE_STYLES: Record<Size, string> = {
+	sm: "h-7 px-2.5 text-[length:var(--size-sm)]",
+	md: "h-[34px] px-3.5 text-[length:var(--size-md)]",
+	lg: "h-10 px-4.5 text-[length:var(--size-md)]",
+};
+
+const ICON_SIZE: Record<Size, "sm" | "md"> = { sm: "sm", md: "md", lg: "md" };
+
+export default function Button({
+	variant = "primary",
+	size = "md",
+	icon,
+	iconRight,
+	href,
+	onClick,
+	disabled = false,
+	autoFocus,
+	children,
+}: ButtonProps) {
+	const className = [
+		"not-prose inline-flex cursor-pointer items-center justify-center gap-2 rounded-md no-underline",
+		"font-sans leading-normal text-[length:var(--size-md)] font-semibold tracking-[var(--tracking-snug)] whitespace-nowrap",
+		"transition-colors duration-150",
+		"focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus-ring)]",
+		"disabled:cursor-not-allowed disabled:opacity-45",
+		VARIANT_STYLES[variant],
+		SIZE_STYLES[size],
+	].join(" ");
+
+	const press = disabled ? undefined : { y: 0.5, scale: 0.988 };
+	const iconSize = ICON_SIZE[size];
+
+	const content = (
+		<>
+			{icon ? <Icon name={icon} size={iconSize} /> : null}
+			{children}
+			{iconRight ? <Icon name={iconRight} size={iconSize} /> : null}
+		</>
+	);
+
+	if (href) {
+		return (
+			<motion.a
+				href={disabled ? undefined : href}
+				aria-disabled={disabled || undefined}
+				whileTap={press}
+				transition={TRANSITIONS.snap}
+				onClick={onClick}
+				className={className}
+			>
+				{content}
+			</motion.a>
+		);
+	}
+
+	return (
+		<motion.button
+			type="button"
+			disabled={disabled}
+			autoFocus={autoFocus}
+			whileTap={press}
+			transition={TRANSITIONS.snap}
+			onClick={onClick}
+			className={className}
+		>
+			{content}
+		</motion.button>
+	);
+}

package/client/builtins/Callout.tsx

@@ -0,0 +1,97 @@
+import type { ReactNode } from "react";
+import { motion } from "framer-motion";
+import { z } from "zod";
+import { fadeRise } from "../motion";
+import { Icon } from "../ui/Icon";
+
+export const calloutProps = z.object({
+	tone: z
+		.enum(["note", "tip", "ok", "warn", "danger"])
+		.default("note")
+		.describe(
+			"Visual intent and icon: note (info), tip (lightbulb), ok (success), warn (caution), or danger (breaking).",
+		),
+	type: z
+		.enum(["info", "warn"])
+		.optional()
+		.describe("Deprecated alias for `tone` (info→note, warn→warn). Prefer `tone`."),
+	title: z
+		.string()
+		.optional()
+		.describe("Optional bold heading shown above the body; defaults to the tone's label."),
+	children: z.custom<ReactNode>().describe("Callout body; any MDX/Markdown content."),
+});
+
+export type CalloutProps = z.infer<typeof calloutProps>;
+
+type Tone = NonNullable<CalloutProps["tone"]>;
+
+const TONES: Record<Tone, { icon: string; bg: string; fg: string; fgVar: string; label: string }> =
+	{
+		note: {
+			icon: "info",
+			bg: "bg-status-info-bg",
+			fg: "text-status-info-fg",
+			fgVar: "var(--status-info-fg)",
+			label: "Note",
+		},
+		tip: {
+			icon: "lightbulb",
+			bg: "bg-surface-accent-soft",
+			fg: "text-text-accent",
+			fgVar: "var(--text-accent)",
+			label: "Tip",
+		},
+		ok: {
+			icon: "circle-check",
+			bg: "bg-status-ok-bg",
+			fg: "text-status-ok-fg",
+			fgVar: "var(--status-ok-fg)",
+			label: "Works",
+		},
+		warn: {
+			icon: "triangle-alert",
+			bg: "bg-status-warn-bg",
+			fg: "text-status-warn-fg",
+			fgVar: "var(--status-warn-fg)",
+			label: "Careful",
+		},
+		danger: {
+			icon: "octagon-alert",
+			bg: "bg-status-danger-bg",
+			fg: "text-status-danger-fg",
+			fgVar: "var(--status-danger-fg)",
+			label: "Breaking",
+		},
+	};
+
+/** `type` is a deprecated alias kept so existing docs written before `tone` keep working. */
+function resolveTone({ tone, type }: Pick<CalloutProps, "tone" | "type">): Tone {
+	if (tone) return tone;
+	if (type === "warn") return "warn";
+	if (type === "info") return "note";
+	return "note";
+}
+
+export default function Callout({ tone, type, title, children }: CalloutProps) {
+	const resolved = resolveTone({ tone, type });
+	const style = TONES[resolved];
+
+	return (
+		<motion.div
+			variants={fadeRise}
+			initial="initial"
+			animate="enter"
+			className={`not-prose flex items-start gap-3 rounded-lg p-4 border border-transparent font-sans font-medium leading-normal text-[length:var(--size-md)] ${style.bg}`}
+			style={{ borderColor: `color-mix(in oklab, ${style.fgVar} 22%, transparent)` }}
+		>
+			<Icon name={style.icon} size="md" className={`mt-0.5 shrink-0 ${style.fg}`} />
+			<div className="min-w-0 flex-1">
+				<p className={`font-bold tracking-[var(--tracking-snug)] ${style.fg}`}>
+					{title || style.label}
+				</p>
+				<div className="mt-1 leading-6 text-text-body">{children}</div>
+			</div>
+		</motion.div>
+	);
+}