fix(admin): refine typography hierarchy (#2252)

* feat(admin): refine typography hierarchy

* docs(admin): remove typography guide

Author: khoinguyenpham04

.changeset/calm-dashboard-type.md

@@ -0,0 +1,5 @@
+---
+"@emdash-cms/admin": patch
+---
+
+Updates the admin Dashboard typography for clearer hierarchy and stable metric and activity values.

.changeset/calm-owls-read.md

@@ -0,0 +1,5 @@
+---
+"@emdash-cms/admin": patch
+---
+
+Updates admin typography with consistent page headings, descriptions, and media library text hierarchy.

e2e/tests/accessibility.spec.ts

@@ -58,6 +58,93 @@ test.describe("Accessibility Audit", () => {
 			expect(results.violations).toEqual([]);
 		});
 
+		test("dashboard card headings and metric values share an inset", async ({ admin }) => {
+			await admin.goToDashboard();
+			await admin.waitForLoading();
+
+			const metricCards = admin.page.getByTestId("dashboard-metric");
+			expect(await metricCards.count()).toBeGreaterThanOrEqual(3);
+
+			const layout = await admin.page.locator("main").evaluate((main) => {
+				const textStart = (element: Element) => {
+					const textNode = [...element.childNodes].find(
+						(node) => node.nodeType === Node.TEXT_NODE && node.textContent?.trim(),
+					);
+					if (!textNode) throw new Error("Dashboard card text is missing");
+					const range = document.createRange();
+					range.selectNodeContents(textNode);
+					const rect = range.getBoundingClientRect();
+					return getComputedStyle(element).direction === "rtl" ? rect.right : rect.left;
+				};
+				const cardStart = (card: Element) => {
+					const rect = card.getBoundingClientRect();
+					return getComputedStyle(card).direction === "rtl" ? rect.right : rect.left;
+				};
+				const contentHeading = [...main.querySelectorAll("h2")].find(
+					(heading) => heading.textContent?.trim() === "Content",
+				);
+				const contentCard = contentHeading?.parentElement?.parentElement;
+				if (!contentHeading || !contentCard) throw new Error("Content card heading is missing");
+				const headingInset = Math.abs(textStart(contentHeading) - cardStart(contentCard));
+
+				const metrics = Array.from(
+					main.querySelectorAll('[data-testid="dashboard-metric"]'),
+					(card) => {
+						const heading = card.querySelector("h2");
+						const value = card.querySelector('[data-testid="dashboard-metric-value"]');
+						if (!heading || !value) throw new Error("Metric label or value is missing");
+
+						return {
+							headingInset: Math.abs(textStart(heading) - cardStart(card)),
+							labelValueGap: Math.abs(textStart(heading) - textStart(value)),
+						};
+					},
+				);
+
+				return { headingInset, metrics };
+			});
+
+			for (const metric of layout.metrics) {
+				expect(metric.headingInset).toBeCloseTo(layout.headingInset, 1);
+				expect(metric.labelValueGap).toBeLessThanOrEqual(0.5);
+			}
+		});
+
+		test("dashboard headings keep the font's default tracking across scripts", async ({
+			admin,
+		}) => {
+			await admin.goToDashboard();
+			await admin.waitForLoading();
+
+			const trackingByLocale = await admin.page.locator("main").evaluate((main) => {
+				const title = main.querySelector("h1");
+				const metricValues = main.querySelectorAll('[data-testid="dashboard-metric-value"]');
+				if (!title || metricValues.length === 0) throw new Error("Dashboard typography is missing");
+
+				const root = document.documentElement;
+				const originalLang = root.lang;
+				const locales = ["en", "ja", "zh-CN"];
+
+				try {
+					return locales.map((locale) => {
+						root.lang = locale;
+						return {
+							locale,
+							title: getComputedStyle(title).letterSpacing,
+							metrics: Array.from(metricValues, (value) => getComputedStyle(value).letterSpacing),
+						};
+					});
+				} finally {
+					root.lang = originalLang;
+				}
+			});
+
+			for (const tracking of trackingByLocale) {
+				expect(tracking.title, tracking.locale).toBe("normal");
+				expect(tracking.metrics, tracking.locale).toEqual(tracking.metrics.map(() => "normal"));
+			}
+		});
+
 		test("content list should have no WCAG 2.x AA violations", async ({ admin }) => {
 			await admin.goToContent("posts");
 			await admin.waitForLoading();
@@ -125,6 +212,55 @@ test.describe("Accessibility Audit", () => {
 			expect(results.violations).toEqual([]);
 		});
 
+		test("page descriptions meet regular-text contrast in the classic light theme", async ({
+			admin,
+			page,
+		}) => {
+			await page.emulateMedia({ colorScheme: "light" });
+			await admin.goto("/plugins-manager");
+			await admin.waitForShell();
+			await admin.waitForLoading();
+
+			const description = page.getByText(
+				"Manage installed plugins. Enable or disable plugins to control their functionality.",
+				{ exact: true },
+			);
+			await expect(description).toBeVisible();
+
+			const contrast = await description.evaluate((element) => {
+				const canvas = document.createElement("canvas");
+				canvas.width = 1;
+				canvas.height = 1;
+				const context = canvas.getContext("2d");
+				if (!context) throw new Error("Canvas context unavailable");
+
+				const toRgb = (color: string) => {
+					context.clearRect(0, 0, 1, 1);
+					context.fillStyle = color;
+					context.fillRect(0, 0, 1, 1);
+					return context.getImageData(0, 0, 1, 1).data;
+				};
+				const luminance = (rgb: Uint8ClampedArray) => {
+					const toLinear = (channel: number) => {
+						const value = channel / 255;
+						return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+					};
+					const red = toLinear(rgb[0] ?? 0);
+					const green = toLinear(rgb[1] ?? 0);
+					const blue = toLinear(rgb[2] ?? 0);
+					return 0.2126 * red + 0.7152 * green + 0.0722 * blue;
+				};
+
+				const foreground = luminance(toRgb(getComputedStyle(element).color));
+				const background = luminance(toRgb(getComputedStyle(document.body).backgroundColor));
+				return (
+					(Math.max(foreground, background) + 0.05) / (Math.min(foreground, background) + 0.05)
+				);
+			});
+
+			expect(contrast).toBeGreaterThanOrEqual(4.5);
+		});
+
 		test("content list should be keyboard navigable", async ({ admin }) => {
 			await admin.goToContent("posts");
 			await admin.waitForLoading();

packages/admin/src/components/ContentList.tsx

@@ -322,7 +322,7 @@ export function ContentList({
 			{/* Header */}
 			<div className="flex items-center justify-between">
 				<div className="flex items-center gap-4">
-					<h1 className="text-2xl font-bold">{collectionLabel}</h1>
+					<h1 className="text-2xl font-semibold leading-tight">{collectionLabel}</h1>
 					{i18n && activeLocale && onLocaleChange && (
 						<LocaleSwitcher
 							locales={i18n.locales}

packages/admin/src/components/ContentTypeEditor.tsx

@@ -351,7 +351,7 @@ export function ContentTypeEditor({
 					) : null
 				}
 			>
-				<h1 className="text-2xl font-bold truncate">
+				<h1 className="truncate text-2xl font-semibold">
 					{isNew ? t`New Content Type` : collection?.label}
 				</h1>
 				{!isNew && (

packages/admin/src/components/ContentTypeList.tsx

@@ -37,8 +37,10 @@ export function ContentTypeList({
 			{/* Header */}
 			<div className="flex items-center justify-between">
 				<div>
-					<h1 className="text-2xl font-bold">{t`Content Types`}</h1>
-					<p className="text-kumo-subtle text-sm">{t`Define the structure of your content`}</p>
+					<h1 className="text-2xl font-semibold leading-tight">{t`Content Types`}</h1>
+					<p className="mt-1 text-sm leading-5 text-pretty text-kumo-subtle">
+						{t`Define the structure of your content`}
+					</p>
 				</div>
 				<RouterLinkButton to="/content-types/new" icon={<Plus />}>
 					{t`New Content Type`}