@podoba/react 0.0.28 → 0.0.30

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@podoba/react",
-	"version": "0.0.28",
+	"version": "0.0.30",
 	"type": "module",
 	"description": "podoba React components — React Aria Components + Tailwind primitives + layout, built with uic.",
 	"repository": {
@@ -16,17 +16,19 @@
 		".": "./src/index.ts"
 	},
 	"files": [
-		"src"
+		"src",
+		"!src/**/*.test.*"
 	],
 	"publishConfig": {
 		"access": "public"
 	},
 	"scripts": {
+		"test": "bun test src",
 		"typecheck": "tsc --build"
 	},
 	"dependencies": {
-		"@podoba/tokens": "^0.0.28",
-		"@podoba/tailwind": "^0.0.28",
+		"@podoba/tokens": "^0.0.30",
+		"@podoba/tailwind": "^0.0.30",
 		"react-aria-components": "1.18.0",
 		"class-variance-authority": "0.7.1",
 		"clsx": "2.1.1",

package/src/components/brand-page-header.tsx

@@ -1,5 +1,6 @@
 import { type ReactNode, useState } from 'react'
 import { Button } from './button'
+import { DisplayHeading } from './text'
 
 /**
  * BrandPageHeader — the brand-workspace page header (port of gs-platform
@@ -30,6 +31,8 @@ export type BrandPageHeaderCrumb = {
 export type BrandPageHeaderProps = {
 	/** The large greeting / page-title slot (e.g. "Good morning Jonas 👋"). */
 	greeting: ReactNode
+	/** Semantic heading level. Use 2 or 3 when the header is nested below a page title. */
+	headingLevel?: 1 | 2 | 3
 	/**
 	 * gs-style "title to go back": a muted, clickable PARENT link rendered as the
 	 * line ABOVE the title (so the title reads "Parent ⏎ Current"). Pass a real
@@ -63,6 +66,7 @@ const PANEL_ID = 'brand-page-header-create-hub'
 
 export function BrandPageHeader({
 	greeting,
+	headingLevel = 1,
 	parentLink,
 	breadcrumbs,
 	cta,
@@ -78,6 +82,7 @@ export function BrandPageHeader({
 	const isControlled = expandedProp !== undefined
 	const expanded = isControlled ? expandedProp : internalExpanded
 	const hasExpandable = Boolean(createHub)
+	const HeadingTag = `h${headingLevel}` as const
 
 	const setExpanded = (next: boolean) => {
 		if (!isControlled) setInternalExpanded(next)
@@ -94,8 +99,8 @@ export function BrandPageHeader({
 				.filter(Boolean)
 				.join(' ')}
 		>
-			<div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:gap-4">
-				<div className="flex min-w-0 flex-1 flex-col gap-1">
+			<div className="flex flex-col gap-2 sm:grid sm:grid-cols-3 sm:items-stretch sm:gap-4">
+				<div className="flex min-w-0 flex-1 flex-col gap-1 sm:col-span-2">
 					{breadcrumbs && breadcrumbs.length > 0 ? (
 						<nav aria-label="Breadcrumb" className="flex flex-wrap items-center gap-1 text-compact text-fg-muted">
 							{breadcrumbs.map((crumb, i) => (
@@ -116,25 +121,27 @@ export function BrandPageHeader({
 							))}
 						</nav>
 					) : null}
-					<h1 className="text-display font-medium leading-[1.12] tracking-wide text-fg">
-						{parentLink ? (
-							// gs "title to go back": muted clickable parent line above the title.
-							// `[&_a]` styles the nested router <Link> (anchor) without @app/ui
-							// importing the router.
-							<>
-								<span className="text-fg-muted transition-colors [&_a:hover]:text-fg [&_a]:text-fg-muted [&_a]:no-underline [&_a]:outline-none [&_a:focus-visible]:underline">
-									{parentLink}
-								</span>
-								<br />
-							</>
-						) : null}
-						{greeting}
-					</h1>
+					<DisplayHeading asChild className="tracking-tight">
+						<HeadingTag>
+							{parentLink ? (
+								// gs "title to go back": muted clickable parent line above the title.
+								// `[&_a]` styles the nested router <Link> (anchor) without @app/ui
+								// importing the router.
+								<>
+									<span className="text-fg-muted transition-colors [&_a:hover]:text-fg [&_a]:text-fg-muted [&_a]:no-underline [&_a]:outline-none [&_a:focus-visible]:underline">
+										{parentLink}
+									</span>
+									<br />
+								</>
+							) : null}
+							{greeting}
+						</HeadingTag>
+					</DisplayHeading>
 				</div>
 
 				{cta ? (
 					// Hero CTA spans 4 of 12 columns (one third) — the greeting takes the rest.
-					<div className="w-full shrink-0 sm:w-1/3">{cta}</div>
+					<div className="h-full min-w-0">{cta}</div>
 				) : ctaLabel ? (
 					<div className="shrink-0">
 						{hasExpandable ? (

package/src/components/button.tsx

@@ -23,7 +23,7 @@ export const Button = uic(RACButton, {
 			// hover neutral-600 (#333333) + `0 0 5px rgba(0,0,0,.5)` shadow → active back
 			// to neutral-400 (surface-inverted, no shadow).
 			primary:
-				'bg-surface-inverted text-fg-inverted hover:bg-neutral-600 hover:shadow-[0_0_5px_0_rgba(0,0,0,0.5)] data-[pressed]:bg-surface-inverted data-[pressed]:shadow-none',
+				'bg-brand-primary text-fg-inverted hover:bg-neutral-600 hover:shadow-[0_0_5px_0_rgba(0,0,0,0.5)] data-[pressed]:bg-brand-primary data-[pressed]:shadow-none',
 			// secondary: #f7f6f2 (surface-card) + 1px #eceae1 (border); hover bg #eceae1
 			// (surface-muted) + border #aba89c (fg-subtle); active bg #eceae1.
 			secondary:
@@ -39,6 +39,9 @@ export const Button = uic(RACButton, {
 			sm: 'py-2 px-4',
 			md: 'py-3 px-6',
 			lg: 'py-4 px-8',
+			// Task/workflow CTA: exact source 44px height, 24px inline padding,
+			// 17/20 medium text.
+			prominent: 'h-11 px-6 py-0 text-panel-heading font-medium',
 		},
 	},
 	defaultVariants: {
@@ -49,5 +52,5 @@ export const Button = uic(RACButton, {
 
 export type ButtonProps = RACButtonProps & {
 	variant?: 'primary' | 'secondary' | 'ghost' | 'destructive'
-	size?: 'sm' | 'md' | 'lg'
+	size?: 'sm' | 'md' | 'lg' | 'prominent'
 }

package/src/components/cta-pill.tsx

@@ -8,15 +8,16 @@ import type { ReactNode } from 'react'
  * translate each per-locale while keeping the middle-word highlight. Presentational
  * only (hard rule #1): every string arrives via props — no i18n, no domain data.
  *
- * a11y NOTE: the background is the light brand-green (#6eddb1); the emphasised word is
- * rendered WHITE per the gs design — white-on-green is ~1.66:1, below WCAG AA, so it
- * reads as a decorative highlight (it also carries a bold weight), not load-bearing
- * copy. The surrounding text stays on the dark `fg` (~10:1).
+ * a11y NOTE: the background is the FIXED light brand-secondary (#6eddb1) — it does
+ * not flip with the theme, so every sentence fragment sits on `fg-on-brand` (stable
+ * dark ink, ~11:1 in both themes). The gs design's white emphasis word failed WCAG AA
+ * (~1.66:1) and turned the whole sentence white-on-green in a dark shell; the
+ * emphasis is now carried by weight alone.
  */
 export interface CtaPillProps {
 	/** Regular lead-in before the emphasised word (e.g. "Let's"). */
 	lead: ReactNode
-	/** The emphasised bold, white middle word (e.g. "create"). */
+	/** The emphasised bold middle word (e.g. "create"). */
 	emphasis: ReactNode
 	/** Regular trailing text after the emphasis (e.g. "something"). */
 	tail: ReactNode
@@ -26,9 +27,9 @@ export interface CtaPillProps {
 
 export function CtaPill({ lead, emphasis, tail, children }: CtaPillProps) {
 	return (
-		<div className="flex w-full items-center justify-between gap-4 rounded-lg bg-brand-secondary px-6 py-4">
-			<p className="min-w-0 text-heading4 font-medium leading-[22px] tracking-normal text-fg">
-				{lead} <span className="font-semibold text-white">{emphasis}</span> {tail}
+		<div className="flex h-full min-h-16 w-full items-center justify-between gap-nav-x rounded-lg bg-brand-green py-2.5 pr-3 pl-4.5">
+			<p className="min-w-0 text-heading4 font-medium leading-5 tracking-tight text-fg-on-brand">
+				{lead} <span className="font-semibold">{emphasis}</span> {tail}
 			</p>
 			<div className="shrink-0">{children}</div>
 		</div>

package/src/components/dialog.tsx

@@ -4,8 +4,8 @@ import {
 	DialogTrigger as RACDialogTrigger,
 	type DialogProps as RACDialogProps,
 	Heading,
-	Modal,
-	ModalOverlay,
+	Modal as RACModal,
+	ModalOverlay as RACModalOverlay,
 } from 'react-aria-components'
 import { uic } from '../utils/uic'
 
@@ -18,25 +18,31 @@ import { uic } from '../utils/uic'
  */
 export const DialogTrigger = RACDialogTrigger
 
-// gs modal backdrop — gs `Dialog.module.scss` overlay: a neutral grey scrim
-// (`rgba(179,179,179,0.5)`) under a light `blur(2px)`.
-const Overlay = uic(ModalOverlay, {
+// Current gs modal backdrop: warm surface-card scrim at 66% under a 10px blur.
+export const ModalOverlay = uic(RACModalOverlay, {
 	displayName: 'DialogOverlay',
 	baseClass:
 		'fixed inset-0 z-50 flex items-center justify-center p-4 ' +
-		'bg-[rgba(179,179,179,0.5)] backdrop-blur-[2px] ' +
-		'data-[entering]:animate-in data-[exiting]:animate-out',
+		'bg-modal-backdrop backdrop-blur-modal-backdrop ' +
+		'data-[entering]:animate-modal-overlay-in data-[exiting]:animate-modal-overlay-out',
 })
 
-// gs content card: white bg, 20px padding (`p-5`), 8px radius (`rounded-lg`), and
-// the gs `Dialog.module.scss` card shadow — a light single-layer
-// `0 2px 8px rgba(0,0,0,.06)`. No border: gs defines the card with the shadow alone.
-const StyledModal = uic(Modal, {
+// gs content card: white bg, 20px padding, 8px radius and the shared two-layer
+// modal elevation.
+export const ModalSurface = uic(RACModal, {
 	displayName: 'DialogModal',
 	baseClass:
-		'rounded-lg bg-surface p-5 outline-none shadow-[0px_2px_8px_0px_rgba(0,0,0,0.06)]',
+		'rounded-lg bg-surface p-5 outline-none shadow-modal-surface ' +
+		'data-[entering]:animate-modal-surface-in data-[exiting]:animate-modal-surface-out',
 })
 
+/**
+ * Unstyled accessible dialog body for edge-to-edge / split modal compositions.
+ * Pair only with the shared {@link ModalOverlay} and {@link ModalSurface}; ordinary
+ * form and confirmation dialogs should use the composed {@link Dialog}.
+ */
+export const ModalDialog = RACDialog
+
 /**
  * Modal width presets. `md` (default) is the form/confirm dialog (gs DialogContent
  * default, 586px); `sm` is a tighter confirm; `lg`/`xl` host wider, taller content
@@ -126,18 +132,14 @@ export const Dialog = ({
 		// when omitted the overlay reads its state from an enclosing DialogTrigger.
 		// Either way the RACDialog render-prop `close` resolves against the active
 		// overlay state, so `close()` works in both modes.
-		<Overlay
-			// Full-screen is an immersive takeover: swap the light 2px scrim for a
-			// heavier backdrop blur so the page behind reads as clearly blurred around
-			// the near-fullscreen canvas. (tailwind-merge dedupes the base blur/scrim.)
-			className={isFlex ? "bg-black/25 backdrop-blur-lg" : undefined}
+		<ModalOverlay
 			isOpen={isOpen}
 			defaultOpen={defaultOpen}
 			onOpenChange={onOpenChange}
 			isDismissable={isDismissable}
 		>
-			<StyledModal className={SIZE_CLASS[size]}>
-				<RACDialog
+			<ModalSurface className={SIZE_CLASS[size]}>
+				<ModalDialog
 					{...props}
 					className={isFlex ? 'flex min-h-0 flex-1 flex-col outline-none' : 'outline-none'}
 				>
@@ -200,8 +202,8 @@ export const Dialog = ({
 							)}
 						</>
 					)}
-				</RACDialog>
-			</StyledModal>
-		</Overlay>
+				</ModalDialog>
+			</ModalSurface>
+		</ModalOverlay>
 	)
 }

package/src/components/input.tsx

@@ -20,20 +20,15 @@ import { uic } from '../utils/uic'
  */
 const StyledInput = uic(RACInput, {
 	displayName: 'InputControl',
-	// White fill so the field reads as editable. The gs original used a cream
-	// (#f7f6f2 → surface-card) fill, but our Card surface is ALSO surface-card, so
-	// a filled field inside a card vanished and read as disabled. Inverted: active
-	// = white (surface), disabled = the muted cream. border #eceae1 → border ·
-	// hover #aba89c → fg-subtle · focus #75e7b8 → brand-green · error → danger.
-	// Identical to textarea.tsx's filled-field skin; `fieldSize` adds the
-	// single-line height (gs sizes the field via padding only).
+	// gs source: borderless cream fill, 8px radius, 14/18 text and 16px inline
+	// padding. Focus keeps an explicit ring for keyboard accessibility.
 	baseClass:
-		'w-full rounded-lg border border-border bg-surface px-4 text-small text-fg ' +
+		'w-full rounded-lg border-0 bg-surface-card px-4 text-small text-fg ' +
 		'outline-none transition-colors duration-200 placeholder:text-fg-muted ' +
-		'data-[hovered]:border-fg-subtle ' +
-		'data-[focused]:border-brand-green data-[focused]:ring-2 data-[focused]:ring-ring ' +
-		'data-[invalid]:border-danger data-[invalid]:ring-danger ' +
-		'data-[disabled]:bg-surface-muted data-[disabled]:opacity-60 data-[disabled]:pointer-events-none',
+		'data-[hovered]:bg-surface-muted ' +
+		'data-[focused]:ring-2 data-[focused]:ring-ring ' +
+		'data-[invalid]:ring-2 data-[invalid]:ring-danger ' +
+		'data-[disabled]:bg-surface-muted data-[disabled]:opacity-50 data-[disabled]:pointer-events-none',
 	variants: {
 		// `fieldSize` (not `size`) to avoid colliding with the native <input size>
 		// attribute, which RAC's Input inherits (a numeric prop).
@@ -41,6 +36,7 @@ const StyledInput = uic(RACInput, {
 			sm: 'h-8',
 			md: 'h-10',
 			lg: 'h-12',
+			tall: 'h-control-tall',
 		},
 	},
 	defaultVariants: {
@@ -56,13 +52,17 @@ export type InputProps = TextFieldProps & {
 	/** Error message; pass a string for a static error or rely on validation. */
 	errorMessage?: string
 	placeholder?: string
-	size?: 'sm' | 'md' | 'lg'
+	size?: 'sm' | 'md' | 'lg' | 'tall'
+	/** Optional class for the TextField root. */
+	rootClassName?: string
+	/** Optional class for the inner native input (for product-specific composition). */
+	inputClassName?: string
 }
 
-export const Input = ({ label, description, errorMessage, placeholder, size, ...props }: InputProps) => (
-	<TextField {...props} className="flex w-full flex-col gap-2">
-		<Label className="text-heading5 font-medium text-fg">{label}</Label>
-		<StyledInput placeholder={placeholder} fieldSize={size} />
+export const Input = ({ label, description, errorMessage, placeholder, size, rootClassName, inputClassName, ...props }: InputProps) => (
+	<TextField {...props} className={`flex w-full flex-col gap-3 ${rootClassName ?? ''}`}>
+		<Label className="text-panel-heading font-medium text-fg">{label}</Label>
+		<StyledInput className={inputClassName} placeholder={placeholder} fieldSize={size} />
 		{description ? (
 			<Text slot="description" className="text-label text-fg-muted">
 				{description}

package/src/components/section-tabs.tsx

@@ -36,6 +36,10 @@ export type SectionTabsProps = {
 	resetLabel?: string
 	/** Glyph for the reset control; defaults to a small grid icon. */
 	resetIcon?: ReactNode
+	/** Visible reset content. When set, renders a source-style text tab (e.g. "Summary"). */
+	resetContent?: ReactNode
+	/** Whether the reset/overview destination is the currently selected section. */
+	isResetSelected?: boolean
 	className?: string
 }
 
@@ -49,12 +53,12 @@ const GridGlyph = () => (
 )
 
 const tabBase =
-	'inline-flex h-7 items-center gap-2 rounded-sm px-3 text-compact text-fg-muted outline-none ' +
-	'transition-colors duration-[120ms] ease-[ease] data-[hovered]:bg-surface-muted data-[hovered]:text-fg ' +
+	'inline-flex h-7 shrink-0 items-center gap-2 rounded-sm px-nav-x py-1.5 text-compact font-normal text-fg-muted outline-none ' +
+	'transition-colors duration-150 ease-in-out data-[hovered]:bg-surface-muted data-[hovered]:text-fg ' +
 	'data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring ' +
 	'data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50 data-[disabled]:bg-transparent data-[disabled]:text-fg-muted'
 
-const tabActive = 'bg-surface-muted font-medium text-fg'
+const tabActive = 'bg-surface-muted text-fg'
 
 export function SectionTabs({
 	tabs,
@@ -64,19 +68,37 @@ export function SectionTabs({
 	onReset,
 	resetLabel = 'Reset',
 	resetIcon,
+	resetContent,
+	isResetSelected = false,
 	className,
 }: SectionTabsProps) {
 	return (
-		<div className={['flex flex-wrap items-center gap-1', className].filter(Boolean).join(' ')} role="group">
+		<div
+			className={[
+				'flex min-h-9 w-full flex-nowrap items-start gap-2 overflow-x-auto pb-2 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden lg:w-2/3 lg:flex-wrap lg:overflow-visible lg:pb-0',
+				className,
+			]
+				.filter(Boolean)
+				.join(' ')}
+			role="group"
+		>
 			{onReset ? (
-				<Button
-					variant="ghost"
-					aria-label={resetLabel}
-					onPress={onReset}
-					className="h-7 w-7 rounded-sm p-0 text-fg-muted data-[hovered]:text-fg"
-				>
-					{resetIcon ?? <GridGlyph />}
-				</Button>
+				<div className="sticky left-0 z-10 shrink-0 bg-surface pr-1 lg:static lg:bg-transparent lg:pr-0">
+					<Button
+						variant="ghost"
+						aria-label={resetLabel}
+						aria-pressed={isResetSelected}
+						onPress={onReset}
+						className={[
+							resetContent ? tabBase : 'h-7 w-7 rounded-sm p-0 text-fg-muted data-[hovered]:text-fg',
+							isResetSelected ? tabActive : '',
+						]
+							.filter(Boolean)
+							.join(' ')}
+					>
+						{resetContent ?? resetIcon ?? <GridGlyph />}
+					</Button>
+				</div>
 			) : null}
 			{tabs.map((tab) => {
 				const selected = active === tab.key

package/src/components/select.tsx

@@ -30,17 +30,15 @@ import { useInFocusOverlay } from './focus-context'
  */
 const SelectTrigger = uic(RACButton, {
 	displayName: 'SelectTrigger',
-	// Sized to match the other form fields (Input / ComboBox): h-12, 16px side
-	// padding, 8px radius. White fill + border so the trigger doesn't vanish inside
-	// a Card (also surface-card) and read as disabled; hover darkens the border.
-	// Error → 2px danger ring driven off the RACSelect root's `data-invalid`.
+	// Exact gs source control: 58px tall, 20px inline padding, borderless cream
+	// fill and 8px radius.
 	baseClass:
-		'flex h-12 w-full items-center justify-between gap-2.5 rounded-lg border border-border bg-surface px-4 ' +
+		'flex h-control-tall w-full items-center justify-between gap-2.5 rounded-lg border-0 bg-surface-card px-5 ' +
 		'text-small text-fg outline-none transition-colors ' +
-		'data-[hovered]:border-fg-subtle ' +
+		'data-[hovered]:bg-surface-muted ' +
 		'data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring ' +
-		'group-data-[invalid]:border-danger group-data-[invalid]:ring-2 group-data-[invalid]:ring-danger ' +
-		'data-[disabled]:bg-surface-muted data-[disabled]:opacity-60 data-[disabled]:pointer-events-none',
+		'group-data-[invalid]:ring-2 group-data-[invalid]:ring-danger ' +
+		'data-[disabled]:bg-surface-muted data-[disabled]:opacity-50 data-[disabled]:pointer-events-none',
 })
 
 export const SelectItem = uic(ListBoxItem, {
@@ -66,6 +64,10 @@ export type SelectProps<T extends object> = RACSelectProps<T> & {
 	 */
 	placeholder: string
 	children: ReactNode
+	/** Optional class for the Select root. */
+	rootClassName?: string
+	/** Optional class for the trigger (for product-specific composition). */
+	triggerClassName?: string
 }
 
 export const Select = <T extends object>({
@@ -74,6 +76,8 @@ export const Select = <T extends object>({
 	errorMessage,
 	placeholder,
 	children,
+	rootClassName,
+	triggerClassName,
 	...props
 }: SelectProps<T>) => {
 	// In a focus overlay, show the options inline (seamless) instead of a popover.
@@ -91,8 +95,8 @@ export const Select = <T extends object>({
 	const err = <FieldError className="text-label text-danger">{errorMessage}</FieldError>
 
 	return (
-		<RACSelect {...props} placeholder={placeholder} className="group flex flex-col gap-2">
-			<Label className="text-heading5 font-medium text-fg">{label}</Label>
+		<RACSelect {...props} placeholder={placeholder} className={`group flex flex-col gap-3 ${rootClassName ?? ''}`}>
+			<Label className="text-panel-heading font-medium text-fg">{label}</Label>
 			{inFocus ? (
 				<>
 					{listbox}
@@ -101,7 +105,7 @@ export const Select = <T extends object>({
 				</>
 			) : (
 				<>
-					<SelectTrigger>
+					<SelectTrigger className={triggerClassName}>
 						<SelectValue className="data-[placeholder]:text-fg-muted" />
 						{/* gs chevron: 9.5px caret, dark (neutral-400 → fg), non-interactive. */}
 						<svg

package/src/components/text.tsx

@@ -20,6 +20,25 @@ import { uic } from '../utils/uic'
  * no i18n.
  */
 
+/**
+ * The large product heading from the GS reference UI (`label-1` in its original
+ * token vocabulary): 30px / 32px / medium with -2px tracking.
+ *
+ * Kept separate from the 28px semantic Heading ramp because it is a reusable
+ * product-display treatment, not a document-outline level. Use `asChild` to project
+ * it onto the correct h1–h6 element.
+ */
+export const DisplayHeading = uic('h2', {
+	displayName: 'DisplayHeading',
+	baseClass: 'text-display-large font-medium text-fg',
+})
+
+/** Compact 17px / 20px section title used in workflow and dialog panels. */
+export const PanelHeading = uic('h3', {
+	displayName: 'PanelHeading',
+	baseClass: 'text-panel-heading font-medium text-fg',
+})
+
 export const Text = uic('span', {
 	displayName: 'Text',
 	baseClass: 'text-fg',

package/src/components/tile.tsx

@@ -31,10 +31,14 @@ export type TileAlign = 'top' | 'center'
 const THEME: Record<TileTheme, string> = {
 	// Light tiles carry a visible hairline; dark/colored use a transparent border so
 	// every tile keeps the same box size (no 1px shift between themes).
+	// Every surface pairs with ITS semantic foreground (never raw white / bare fg):
+	// `surface-inverted` flips with the theme so it needs the flipping `fg-inverted`;
+	// teal/yellow are FIXED light surfaces so they need the stable `fg-on-brand` ink
+	// (theme-flipping `fg` went white-on-pastel in a dark shell).
 	light: 'border border-border bg-surface-card text-fg',
-	dark: 'border border-transparent bg-surface-inverted text-white',
-	teal: 'border border-transparent bg-brand-secondary text-fg',
-	yellow: 'border border-transparent bg-accent-yellow text-fg',
+	dark: 'border border-transparent bg-surface-inverted text-fg-inverted',
+	teal: 'border border-transparent bg-brand-secondary text-fg-on-brand',
+	yellow: 'border border-transparent bg-accent-yellow text-fg-on-brand',
 }
 
 // The shared inner for EVERY tile (gs `DashboardContentCard`): 16px padding
@@ -95,10 +99,23 @@ export type TileProps = {
 export const tileStatClass = 'text-display font-medium leading-[30px] tracking-wide'
 
 function titleTone(theme: TileTheme, subtle: boolean): string {
-	if (theme === 'dark') return subtle ? 'text-white/60' : 'text-white'
+	if (theme === 'dark') return subtle ? 'text-fg-inverted/60' : 'text-fg-inverted'
+	if (theme === 'teal' || theme === 'yellow') return subtle ? 'text-fg-on-brand/70' : 'text-fg-on-brand'
 	return subtle ? 'text-fg-muted' : 'text-fg'
 }
 
+/**
+ * Muted supporting text / footer tone per surface. `fg-muted` is tuned for white —
+ * on the colored surfaces it drops below AA, so those blend their own paired ink
+ * instead (/60 · /70 keep ≥4.5:1 in both themes — verified by the contrast test
+ * in @podoba/tokens).
+ */
+function mutedTone(theme: TileTheme): string {
+	if (theme === 'dark') return 'text-fg-inverted/60'
+	if (theme === 'teal' || theme === 'yellow') return 'text-fg-on-brand/70'
+	return 'text-fg-muted'
+}
+
 /** head / content / tail bands — the normal (non-media) layout. */
 function TileBands({
 	theme,
@@ -123,7 +140,7 @@ function TileBands({
 		) : null
 	const textNode =
 		text != null ? (
-			<p className={`text-small leading-4 ${theme === 'dark' ? 'text-white/60' : 'text-fg-muted'} ${title != null ? 'mt-3' : ''}`}>
+			<p className={`text-small leading-4 ${mutedTone(theme)} ${title != null ? 'mt-3' : ''}`}>
 				{text}
 			</p>
 		) : null
@@ -153,8 +170,9 @@ function TileBands({
 	}
 
 	// Footer defaults to 14px muted (gs supporting text); self-styled footer content
-	// (links, buttons) overrides both size and colour.
-	const footerTone = theme === 'dark' ? 'text-white/50' : theme === 'light' ? 'text-fg-muted' : 'text-fg/70'
+	// (links, buttons) overrides both size and colour. Shares `mutedTone` — the old
+	// white/50 (dark) and fg/70 (teal/yellow) both broke AA in a dark shell.
+	const footerTone = mutedTone(theme)
 
 	return (
 		<>
@@ -197,7 +215,7 @@ function MediaHero({
 
 	return (
 		<div
-			className={['relative isolate h-full min-h-[200px] w-full overflow-hidden rounded-lg bg-surface-inverted', className]
+			className={['@container relative isolate h-full min-h-[200px] w-full overflow-hidden rounded-lg bg-surface-inverted', className]
 				.filter(Boolean)
 				.join(' ')}
 		>
@@ -239,20 +257,36 @@ function MediaHero({
 						/>
 					) : null}
 
-					{eyebrow ? (
-						<span className="pointer-events-none absolute left-6 top-6 z-10 text-compact font-medium text-white">{eyebrow}</span>
-					) : null}
-
-					{/* Content is click-through so pressing the title/badge falls to the
-					    press overlay; only `footer` re-enables its own pointer events. */}
-					<div className="pointer-events-none absolute inset-x-6 bottom-6 z-10 flex flex-col gap-4">
-						{title ? <h2 className="max-w-md text-display font-medium leading-tight text-white">{title}</h2> : null}
-						{footer != null || badge != null ? (
-							<div className="flex items-center justify-between gap-4">
-								<span className="pointer-events-auto">{footer}</span>
-								<span>{badge}</span>
-							</div>
+					{/* Keep every text overlay in one flex flow. The old independent
+					    top eyebrow and bottom title bands could overlap when a long title
+					    wrapped on a narrow card. Compact mobile insets/type preserve the
+					    200px floor; the spacious composition returns when the card itself,
+					    rather than merely the viewport, is wide enough. */}
+					<div
+						data-slot="media-overlay"
+						className="pointer-events-none absolute inset-4 z-10 flex min-h-0 flex-col @sm:inset-6"
+					>
+						{eyebrow ? (
+							<span data-slot="media-eyebrow" className="shrink-0 text-compact font-medium text-white">
+								{eyebrow}
+							</span>
 						) : null}
+
+						{/* Content is click-through so pressing the title/badge falls to the
+						    press overlay; only `footer` re-enables its own pointer events. */}
+						<div data-slot="media-content" className="mt-auto flex min-h-0 flex-col gap-2 @sm:gap-4">
+							{title ? (
+								<h2 className="max-w-md text-title font-medium leading-tight text-white @sm:text-display">
+									{title}
+								</h2>
+							) : null}
+							{footer != null || badge != null ? (
+								<div className="flex items-center justify-between gap-3 @sm:gap-4">
+									<span className="pointer-events-auto">{footer}</span>
+									<span>{badge}</span>
+								</div>
+							) : null}
+						</div>
 					</div>
 				</>
 			)}
@@ -350,10 +384,14 @@ export type BadgeColor = 'green' | 'yellow' | 'grey' | 'dark'
 const BADGE: Record<BadgeColor, string> = {
 	// gs `GSTag` green = the brand green (not the pale accent-mint). One saturated
 	// brand green for every green tag (New, Active, Published), matching gs 1:1.
-	green: 'bg-brand-green text-fg',
-	yellow: 'bg-accent-yellow text-fg',
-	grey: 'bg-surface-muted text-fg-muted',
-	dark: 'bg-surface-inverted text-white',
+	// Pairing rule (same as Tile THEME): fixed light surfaces take the stable
+	// `fg-on-brand` ink, the flipping inverted surface takes `fg-inverted`, and grey
+	// takes full `fg` — `fg-muted` on `surface-muted` was ~3.7:1, under the 4.5:1
+	// AA floor for caption-size text.
+	green: 'bg-brand-green text-fg-on-brand',
+	yellow: 'bg-accent-yellow text-fg-on-brand',
+	grey: 'bg-surface-muted text-fg',
+	dark: 'bg-surface-inverted text-fg-inverted',
 }
 
 export function Badge({ label, color = 'grey' }: { label: ReactNode; color?: BadgeColor }) {

package/src/utils/uic.ts

@@ -58,12 +58,15 @@ const twMerge = extendTailwindMerge({
 						'caption',
 						'label',
 						'compact',
+						'small',
 						'callout',
 						'body',
 						'subtitle',
 						'title',
 						'headline',
 						'display',
+						'display-large',
+						'panel-heading',
 						// Heading ramp (size + line-height).
 						'heading1',
 						'heading2',
@@ -75,7 +78,7 @@ const twMerge = extendTailwindMerge({
 			],
 		},
 		theme: {
-			spacing: ['nav-x'],
+			spacing: ['nav-x', 'control-tall'],
 			// Custom card/panel radius key (rounded-panel) → dedupes against other
 			// rounded-* utilities. xl/2xl are stock keys tailwind-merge already knows.
 			radius: ['panel'],