@delacour/react-native-ui 0.1.0 → 0.2.0-alpha.20261010061731

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0",
+	"version": "0.2.0-alpha.20261010061731",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -110,7 +110,7 @@
 		"gen-exports": "bun scripts/gen-exports.ts"
 	},
 	"dependencies": {
-		"clsx": "^2.1.1",
+		"cn": "^0.4.0",
 		"tailwind-merge": "^3.6.0",
 		"tailwind-variants": "^3.3.1"
 	},

package/src/components/badge/AGENTS.md

@@ -86,3 +86,8 @@ A compact label for status, category or count. Compound root plus `Badge.Label`,
 - **String children** are wrapped in a `Badge.Label` automatically, consecutive
   strings collapsing into one — the same rule, and the same reason, as
   [`Button`](../button/AGENTS.md).
+
+- **`material="etched"` squares the capsule and tints.** The root and the close button take
+  `rounded-sm`; `soft` status fills become `bg-<status>/8` in light and `/16` in dark, written out
+  per colour because Tailwind's scanner cannot see a built class. The material rides the badge
+  context so the close button follows the root.

package/src/components/badge/badge-close-button.tsx

@@ -30,13 +30,13 @@ export function BadgeCloseButton({
 	feedback = "fade",
 	...props
 }: BadgeCloseButtonProps): ReactElement {
-	const { size, isDisabled } = useBadgePart("Badge.CloseButton");
+	const { size, isDisabled, material } = useBadgePart("Badge.CloseButton");
 
 	return (
 		<Pressable
 			accessibilityLabel={accessibilityLabel}
 			accessibilityRole="button"
-			className={badgeVariants({ size }).closeButton({ className })}
+			className={badgeVariants({ material, size }).closeButton({ className })}
 			disabled={isDisabled}
 			feedback={feedback}
 			{...props}

package/src/components/badge/badge.context.tsx

@@ -1,5 +1,5 @@
 import { createContext, type ReactElement, type ReactNode, use } from "react";
-import type { BadgeColor, BadgeSize, BadgeVariant } from "./badge.variants";
+import type { BadgeColor, BadgeMaterial, BadgeSize, BadgeVariant } from "./badge.variants";
 
 export type BadgeContextValue = {
 	/** Size of the badge. */
@@ -10,6 +10,7 @@ export type BadgeContextValue = {
 	color: BadgeColor;
 	/** Whether the badge is disabled. */
 	isDisabled: boolean;
+	material: BadgeMaterial;
 };
 
 const BadgeContext = createContext<BadgeContextValue | null>(null);

package/src/components/badge/badge.tsx

@@ -7,6 +7,7 @@ import { type BadgeContextValue, BadgeProvider } from "./badge.context";
 import {
 	BADGE_FOREGROUND_TOKEN,
 	type BadgeColor,
+	type BadgeMaterial,
 	type BadgeSize,
 	type BadgeVariant,
 	badgeVariants,
@@ -23,6 +24,8 @@ export type BadgeProps = Omit<PressableProps, "asChild" | "busy" | "children" |
 	/** What the surface means. */
 	color?: BadgeColor;
 	size?: BadgeSize;
+	/** `flat` by default, a capsule. `etched` squares the corner and tints soft status fills as an alpha. */
+	material?: BadgeMaterial;
 	isDisabled?: boolean;
 	/** Composes a trailing dismiss control in. Its press never reaches `onPress`. */
 	onClose?: () => void;
@@ -36,6 +39,7 @@ export type BadgeProps = Omit<PressableProps, "asChild" | "busy" | "children" |
 function BadgeRoot({
 	variant = "solid",
 	color = "default",
+	material = "flat",
 	size = "md",
 	isDisabled = false,
 	onClose,
@@ -52,11 +56,11 @@ function BadgeRoot({
 	...props
 }: BadgeProps): ReactElement {
 	const context = useMemo<BadgeContextValue>(
-		() => ({ variant, color, size, isDisabled }),
-		[variant, color, size, isDisabled]
+		() => ({ variant, color, size, isDisabled, material }),
+		[variant, color, size, isDisabled, material]
 	);
 
-	const slots = badgeVariants({ color, isDisabled, size, variant });
+	const slots = badgeVariants({ color, isDisabled, material, size, variant });
 
 	// Icons composed into the badge adopt these unless told otherwise.
 	const iconClassName = slots.icon();

package/src/components/badge/badge.variants.test.ts

@@ -267,3 +267,29 @@ describe("resolveBadgeInteractive", () => {
 		expect(resolveBadgeInteractive({ onPress: noop, onLongPress: noop })).toBe(true);
 	});
 });
+
+describe("the etched badge material", () => {
+	test("flat keeps the capsule", () => {
+		expect(badgeVariants({}).root()).toContain("rounded-full");
+	});
+
+	test("etched squares the corner to the small step", () => {
+		const cls = badgeVariants({ material: "etched" }).root();
+		expect(cls).toContain("rounded-sm");
+		expect(cls).not.toContain("rounded-full");
+		expect(badgeVariants({ material: "etched" }).closeButton()).toContain("rounded-sm");
+	});
+
+	test("etched soft status fills are alpha tints of the status colour", () => {
+		for (const [color, fill] of [
+			["success", "bg-success/8"],
+			["warning", "bg-warning/8"],
+			["destructive", "bg-destructive/8"],
+			["info", "bg-info/8"],
+		] as const) {
+			const cls = badgeVariants({ color, material: "etched", variant: "soft" }).root();
+			expect(cls).toContain(fill);
+			expect(cls).toContain(`dark:${fill.replace("/8", "/16")}`);
+		}
+	});
+});

package/src/components/badge/badge.variants.ts

@@ -7,10 +7,18 @@ export const BADGE_VARIANTS = ["solid", "soft", "outline", "ghost"] as const;
 /** What the surface means. Orthogonal to {@link BADGE_VARIANTS}. */
 export const BADGE_COLORS = ["default", "primary", "success", "warning", "destructive", "info"] as const;
 
+/**
+ * `flat` is the library default, a capsule. `etched` squares it to the small
+ * corner and tints the status fills as a low alpha of the status colour, so a
+ * badge sits quietly on any surface it lands on.
+ */
+export const BADGE_MATERIALS = ["flat", "etched"] as const;
+
 export const BADGE_SIZES = ["sm", "md", "lg"] as const;
 
 export type BadgeVariant = (typeof BADGE_VARIANTS)[number];
 export type BadgeColor = (typeof BADGE_COLORS)[number];
+export type BadgeMaterial = (typeof BADGE_MATERIALS)[number];
 export type BadgeSize = (typeof BADGE_SIZES)[number];
 
 /**
@@ -148,6 +156,7 @@ export const badgeVariants = tv({
 				icon: "size-icon-md",
 			},
 		},
+		material: { flat: {}, etched: {} },
 		// The empty `false` branch is load-bearing typing, not a placeholder.
 		// See the note in button.variants.ts.
 		isDisabled: { true: { root: "opacity-50" }, false: {} },
@@ -204,6 +213,18 @@ export const badgeVariants = tv({
 		{ variant: "ghost", color: "warning", class: { label: "text-warning-soft-foreground" } },
 		{ variant: "ghost", color: "destructive", class: { label: "text-destructive-soft-foreground" } },
 		{ variant: "ghost", color: "info", class: { label: "text-info-soft-foreground" } },
+
+		// Written out per colour: Tailwind's scanner cannot see `bg-${color}/8`.
+		{ material: "etched", class: { root: "rounded-sm", closeButton: "rounded-sm" } },
+		{ material: "etched", variant: "soft", color: "success", class: { root: "bg-success/8 dark:bg-success/16" } },
+		{ material: "etched", variant: "soft", color: "warning", class: { root: "bg-warning/8 dark:bg-warning/16" } },
+		{
+			material: "etched",
+			variant: "soft",
+			color: "destructive",
+			class: { root: "bg-destructive/8 dark:bg-destructive/16" },
+		},
+		{ material: "etched", variant: "soft", color: "info", class: { root: "bg-info/8 dark:bg-info/16" } },
 	],
 	defaultVariants: {
 		variant: "solid",

package/src/components/button/AGENTS.md

@@ -249,3 +249,9 @@ for a chunk that says something rather than doing something. An
   than `primary` when nothing names a variant: a chunk that cannot be pressed
   should not wear the group's action paint. A group that *does* name a variant
   is followed, so an outline run reads as one piece.
+
+- **`material="etched"` is opt-in and per fill.** `primary` takes `shadow-etched-primary` (a white
+  inset top edge at 16%); `secondary`, `tertiary` and `outline` take the light/dark edge
+  (`shadow-etched dark:shadow-etched-dark`); `ghost`, `destructive` and `destructive-soft` stay flat
+  — a ghost has no surface to lift and a signal colour does not take a second highlight. The press
+  scale is already 0.97. The tokens live in `tokens.css`.

package/src/components/button/button.tsx

@@ -7,6 +7,7 @@ import { type ButtonContextValue, ButtonProvider, useButtonGroupItemContext } fr
 import {
 	BUTTON_FOREGROUND_TOKEN,
 	type ButtonLayout,
+	type ButtonMaterial,
 	type ButtonSize,
 	type ButtonSpinnerPlacement,
 	type ButtonVariant,
@@ -23,6 +24,8 @@ import { ButtonStartContent } from "./button-start-content";
 
 export type ButtonProps = Omit<PressableProps, "busy" | "children" | "disabled" | "pressedOpacity" | "pressedScale"> & {
 	variant?: ButtonVariant;
+	/** `flat` by default; `etched` sets a highlight into the fill's edge. */
+	material?: ButtonMaterial;
 	/** Height, label step, icon step, corner and padding on one axis. `icon-*` is a square. */
 	size?: ButtonSize;
 	isDisabled?: boolean;
@@ -37,6 +40,7 @@ export type ButtonProps = Omit<PressableProps, "busy" | "children" | "disabled"
 
 function ButtonRoot({
 	variant,
+	material = "flat",
 	size,
 	isDisabled,
 	isLoading = false,
@@ -75,6 +79,7 @@ function ButtonRoot({
 		isLoading,
 		isSeamed: item?.isSeamed ?? false,
 		isStretched: item?.isStretched ?? false,
+		material,
 		orientation: item?.orientation ?? "horizontal",
 		size: resolvedSize,
 		variant: resolvedVariant,

package/src/components/button/button.variants.test.ts

@@ -8,6 +8,7 @@ import {
 	BUTTON_GROUP_SEPARATOR_ORIENTATION,
 	BUTTON_ICON_SIZES,
 	BUTTON_LABEL_SIZES,
+	BUTTON_MATERIALS,
 	BUTTON_SIZES,
 	BUTTON_SPINNER_PLACEMENTS,
 	BUTTON_VARIANTS,
@@ -812,6 +813,41 @@ describe("resolveGroupedButtonSize", () => {
 	});
 });
 
+describe("the etched button material", () => {
+	test("flat is the default and adds no shadow", () => {
+		for (const variant of BUTTON_VARIANTS) {
+			expect(buttonVariants({ variant }).root()).toBe(buttonVariants({ variant, material: "flat" }).root());
+			expect(buttonVariants({ variant }).root()).not.toMatch(/shadow/);
+		}
+	});
+
+	test("etched primary carries the white inset highlight", () => {
+		const cls = buttonVariants({ material: "etched", variant: "primary" }).root();
+		expect(cls).toContain("shadow-etched-primary");
+		expect(cls).not.toContain("shadow-etched ");
+	});
+
+	test("etched filled and outlined buttons carry the light and dark edge", () => {
+		for (const variant of ["secondary", "tertiary", "outline"] as const) {
+			const cls = buttonVariants({ material: "etched", variant }).root();
+			expect(cls).toContain("shadow-etched");
+			expect(cls).toContain("dark:shadow-etched-dark");
+		}
+	});
+
+	// A ghost has no surface to lift, and a destructive fill is a signal colour
+	// whose highlight would read as a second state.
+	test("ghost and destructive variants stay flat", () => {
+		for (const variant of ["ghost", "destructive", "destructive-soft"] as const) {
+			expect(buttonVariants({ material: "etched", variant }).root()).not.toMatch(/shadow/);
+		}
+	});
+
+	test("lists every material", () => {
+		expect(BUTTON_MATERIALS).toEqual(["flat", "etched"]);
+	});
+});
+
 describe("a detached group", () => {
 	test("places every member on its own", () => {
 		// `only` is the lone member's position and draws the lone button's corner,

package/src/components/button/button.variants.ts

@@ -13,6 +13,14 @@ export const BUTTON_VARIANTS = [
 ] as const;
 
 /** Sizes that hold a label. Horizontal padding; the width comes from the content. */
+/**
+ * `flat` is the library default. `etched` sets the highlight into the fill's
+ * edge — a white inset top edge on `primary`, the light/dark edge on the quiet
+ * fills. Ghost and destructive buttons stay flat: a ghost has no surface to
+ * lift, and a signal colour does not take a second highlight.
+ */
+export const BUTTON_MATERIALS = ["flat", "etched"] as const;
+
 export const BUTTON_LABEL_SIZES = ["sm", "md", "lg"] as const;
 
 /** Sizes with a square footprint, for a button whose only content is an icon. */
@@ -33,6 +41,7 @@ export const BUTTON_GROUP_ORIENTATIONS = ["horizontal", "vertical"] as const;
 
 export const BUTTON_GROUP_POSITIONS = ["first", "middle", "last", "only"] as const;
 
+export type ButtonMaterial = (typeof BUTTON_MATERIALS)[number];
 export type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
 export type ButtonLabelSize = (typeof BUTTON_LABEL_SIZES)[number];
 export type ButtonIconSize = (typeof BUTTON_ICON_SIZES)[number];
@@ -217,6 +226,7 @@ export const buttonVariants = tv({
 		// orientation, so it lands here rather than in six compound cells that
 		// would all say the same word.
 		groupPosition: { none: {}, first: {}, middle: { root: "rounded-none" }, last: {}, only: {} },
+		material: { flat: {}, etched: {} },
 		// The empty `false` branches are load-bearing typing, not placeholders.
 		// `tv` derives the prop type from the declared keys, so a map with only
 		// `true` types the prop as `true` rather than `boolean` and rejects
@@ -229,6 +239,12 @@ export const buttonVariants = tv({
 		isDimmedWhileLoading: { true: {}, false: {} },
 	},
 	compoundVariants: [
+		{ material: "etched", variant: "primary", class: { root: "shadow-etched-primary" } },
+		{
+			material: "etched",
+			variant: ["secondary", "tertiary", "outline"],
+			class: { root: "shadow-etched dark:shadow-etched-dark" },
+		},
 		// Loading is not a disabled state. The button keeps full contrast — the
 		// spinner already says the press landed — unless the caller opts in.
 		{ isLoading: true, isDimmedWhileLoading: true, class: { root: "opacity-50" } },

package/src/components/card/AGENTS.md

@@ -86,3 +86,7 @@ A content surface with a header, a body and a footer, built on
   that knows what the press means. The playground's plan picker is the example.
 - **No text treatment on the root, header, content or footer** (rule 1). The
   tests assert it across every combination.
+
+- **`material` passes straight to `Surface`.** `etched` lifts the card with the edge highlight;
+  `tray` frames panels. A card inside a tray takes the xl corner and the card fill. Pair `etched`
+  with `className="rounded-2xl"` for the 18-point corner; the radius is not part of the material.

package/src/components/card/card.tsx

@@ -15,19 +15,25 @@ export type CardProps = Omit<SurfaceProps, "padding"> & {
 	size?: CardSize;
 };
 
-function CardRoot({ variant, size = "md", className, children, ...props }: CardProps): ReactElement {
+function CardRoot({ variant, material = "flat", size = "md", className, children, ...props }: CardProps): ReactElement {
 	const parentPlane = useSurfaceContext()?.plane ?? null;
 
 	// Resolved here as well as inside `Surface`, because the parts need the plane
 	// the card landed on — the title's colour and a band footer's fill key off it.
 	const resolved = resolveSurfaceVariant({ parentPlane, variant });
-	const plane = resolveSurfacePlane({ parentPlane, variant: resolved });
+	const plane = resolveSurfacePlane({ material, parentPlane, variant: resolved });
 
 	const context = useMemo<CardContextValue>(() => ({ plane, size, variant: resolved }), [plane, size, resolved]);
 
 	return (
 		<CardProvider value={context}>
-			<Surface className={cardVariants({ size }).root({ className })} padding="none" variant={resolved} {...props}>
+			<Surface
+				className={cardVariants({ size }).root({ className })}
+				material={material}
+				padding="none"
+				variant={resolved}
+				{...props}
+			>
 				{children}
 			</Surface>
 		</CardProvider>

package/src/components/input/AGENTS.md

@@ -124,3 +124,8 @@ reads as one control rather than two boxes touching.
   wins. Disabled is the outermost rung of an already-three-deep ladder
   (`Input.Group` → own prop → `Field` → `Button.Group`), so a single field in a
   run can still be the only one disabled.
+
+- **`variant="etched"` is the opt-in devl field.** `border-input bg-card` with the light/dark edge
+  highlight; focus swaps it for `border-ring` and a 3pt neutral halo (`shadow-focus`, `-dark`).
+  The halo is a plain alpha, not `color-mix` on the ring: `color-mix` inside a `box-shadow` does not
+  survive Uniwind's compile and draws nothing. Invalid keeps the highlight and the destructive border.

package/src/components/input/input.variants.test.ts

@@ -367,3 +367,35 @@ describe("a joined field's corner", () => {
 		}
 	});
 });
+
+describe("the etched input variant", () => {
+	test("is listed after the two flat variants", () => {
+		expect(INPUT_VARIANTS).toEqual(["primary", "secondary", "etched"]);
+	});
+
+	test("is a card fill with the input border and the light and dark edge", () => {
+		const cls = inputVariants({ variant: "etched" }).root();
+		expect(cls).toContain("bg-card");
+		expect(cls).toContain("border-input");
+		expect(cls).toContain("shadow-etched");
+		expect(cls).toContain("dark:shadow-etched-dark");
+	});
+
+	test("focus swaps the border to the ring and adds the 3px halo", () => {
+		const cls = inputVariants({ isFocused: true, variant: "etched" }).root();
+		expect(cls).toContain("border-ring");
+		expect(cls).toContain("shadow-focus");
+		expect(cls).toContain("dark:shadow-focus-dark");
+		expect(cls).not.toContain("shadow-etched");
+	});
+
+	test("invalid outranks focus", () => {
+		const cls = inputVariants({ isFocused: true, isInvalid: true, variant: "etched" }).root();
+		expect(cls).toContain("border-destructive");
+		expect(cls).not.toContain("shadow-focus");
+	});
+
+	test("the flat variants draw no shadow", () => {
+		expect(inputVariants({ isFocused: true, variant: "primary" }).root()).not.toMatch(/shadow/);
+	});
+});

package/src/components/input/input.variants.ts

@@ -3,7 +3,7 @@ import { cn } from "../../lib/cn";
 import { tv } from "../../lib/tv";
 import type { ButtonGroupOrientation, ButtonGroupSlotPosition } from "../button/button.variants";
 
-export const INPUT_VARIANTS = ["primary", "secondary"] as const;
+export const INPUT_VARIANTS = ["primary", "secondary", "etched"] as const;
 
 export const INPUT_SIZES = ["sm", "md", "lg"] as const;
 
@@ -79,6 +79,9 @@ export const inputVariants = tv({
 		variant: {
 			primary: { root: "border-input bg-card" },
 			secondary: { root: "border-transparent bg-secondary" },
+			// The card fill with the highlight set into its edge. Focus swaps
+			// that for a ring border and a three-point halo — see the compound.
+			etched: { root: "border-input bg-card shadow-etched dark:shadow-etched-dark" },
 		},
 		size: {
 			sm: {
@@ -145,6 +148,15 @@ export const inputVariants = tv({
 		// field that went grey the moment it was tapped would drop the only
 		// signal it has that its value is wrong, exactly while it is being fixed.
 		{ isFocused: true, isInvalid: true, class: { root: "border-destructive" } },
+		// An etched field trades its edge highlight for the halo while it holds
+		// focus. Invalid keeps the highlight and the destructive border instead,
+		// so a wrong value never glows in the ring's colour.
+		{
+			isFocused: true,
+			isInvalid: false,
+			variant: "etched",
+			class: { root: "border-ring shadow-focus dark:shadow-focus-dark" },
+		},
 		// The corner a lone field draws: the generic ramp, deliberately not the
 		// button's, because a field and the button beside it are meant to be
 		// retunable apart. `sm` steps down a notch; the other two share `lg`.

package/src/components/surface/AGENTS.md

@@ -70,3 +70,13 @@ components built on it (`Card`, `Alert`) can read the plane they sit on.
 - **No role.** A surface is layout, not a landmark; it adds nothing a screen
   reader could announce. `ViewProps` pass through, so a caller that does mean
   one — `accessibilityRole="summary"` — sets it.
+
+- **`material` is what the surface is made of, separate from which plane it fills.** `flat` is the
+  default and draws nothing extra. `etched` adds `shadow-etched dark:shadow-etched-dark`: a one-pixel
+  highlight set into the edge (a darkening on the bottom in light, a lightening on the top in dark)
+  and a very soft drop. `tray` is the muted frame that holds panels — `bg-muted/70`, `p-1`,
+  `rounded-2xl`, whatever `padding` says. A tray paints its own fill, so it resets the plane to
+  `null` (`resolveSurfacePlane`) and a surface inside it resolves to the card fill, not the next rung
+  down; `SurfaceContext.material` is how that panel knows to take `rounded-xl`, one step under the
+  tray's corner. A single `shadow-*` utility sets one `box-shadow`, which is why light and dark are
+  two tokens joined by `dark:` and not one composed class. Opt-in: nothing in the default look uses it.

package/src/components/surface/surface.context.tsx

@@ -1,5 +1,5 @@
 import { createContext, type ReactElement, type ReactNode, use } from "react";
-import type { SurfacePlane, SurfaceVariant } from "./surface.variants";
+import type { SurfaceMaterial, SurfacePlane, SurfaceVariant } from "./surface.variants";
 
 export type SurfaceContextValue = {
 	/** The fill the enclosing surface resolved to — explicit, or stepped from its own parent. */
@@ -10,6 +10,8 @@ export type SurfaceContextValue = {
 	 * plane beneath it through — `null` when there is none.
 	 */
 	plane: SurfacePlane | null;
+	/** What the surface is made of. A `tray` tells the panels inside it to take the inner corner. */
+	material: SurfaceMaterial;
 };
 
 const SurfaceContext = createContext<SurfaceContextValue | null>(null);

package/src/components/surface/surface.tsx

@@ -4,6 +4,7 @@ import { type SurfaceContextValue, SurfaceProvider, useSurfaceContext } from "./
 import {
 	resolveSurfacePlane,
 	resolveSurfaceVariant,
+	type SurfaceMaterial,
 	type SurfacePadding,
 	type SurfaceVariant,
 	surfaceVariants,
@@ -17,6 +18,8 @@ export type SurfaceProps = ViewProps & {
 	variant?: SurfaceVariant;
 	/** Inner spacing. `none` also clips, for content bled to the corners. */
 	padding?: SurfacePadding;
+	/** `flat` by default. `etched` sets a highlight into the edge; `tray` is the muted frame that holds panels. */
+	material?: SurfaceMaterial;
 	className?: string;
 	children?: ReactNode;
 };
@@ -50,18 +53,32 @@ export type SurfaceProps = ViewProps & {
  *   <Image className="h-40 w-full" source={cover} />
  * </Surface>
  */
-export function Surface({ variant, padding = "md", className, children, ...props }: SurfaceProps): ReactElement {
+export function Surface({
+	variant,
+	padding = "md",
+	material = "flat",
+	className,
+	children,
+	...props
+}: SurfaceProps): ReactElement {
 	const parent = useSurfaceContext();
 	const parentPlane = parent?.plane ?? null;
 
 	const resolved = resolveSurfaceVariant({ parentPlane, variant });
-	const plane = resolveSurfacePlane({ parentPlane, variant: resolved });
+	const plane = resolveSurfacePlane({ material, parentPlane, variant: resolved });
+	const inTray = parent?.material === "tray";
 
-	const context = useMemo<SurfaceContextValue>(() => ({ plane, variant: resolved }), [plane, resolved]);
+	const context = useMemo<SurfaceContextValue>(
+		() => ({ material, plane, variant: resolved }),
+		[material, plane, resolved]
+	);
 
 	return (
 		<SurfaceProvider value={context}>
-			<View className={surfaceVariants({ padding, variant: resolved }).root({ className })} {...props}>
+			<View
+				className={surfaceVariants({ inTray, material, padding, variant: resolved }).root({ className })}
+				{...props}
+			>
 				{children}
 			</View>
 		</SurfaceProvider>

package/src/components/surface/surface.variants.test.ts

@@ -6,6 +6,7 @@ import {
 	resolveSurfaceVariant,
 	SURFACE_FILLED_VARIANTS,
 	SURFACE_FOREGROUND_TOKENS,
+	SURFACE_MATERIALS,
 	SURFACE_PADDINGS,
 	SURFACE_VARIANTS,
 	surfaceVariants,
@@ -178,3 +179,49 @@ describe("resolveSurfacePlane", () => {
 		expect(resolveSurfaceVariant({ parentPlane: through })).toBe("secondary");
 	});
 });
+
+describe("surface materials", () => {
+	test("flat is the default and adds nothing", () => {
+		expect(surfaceVariants().root()).toBe(surfaceVariants({ material: "flat" }).root());
+		expect(surfaceVariants().root()).not.toMatch(/shadow/);
+	});
+
+	test("etched lifts the edge with the light and dark highlight", () => {
+		const cls = surfaceVariants({ material: "etched" }).root();
+		expect(cls).toContain("shadow-etched");
+		expect(cls).toContain("dark:shadow-etched-dark");
+		expect(cls).toContain("bg-card");
+	});
+
+	test("a tray is a muted, squarely padded 2xl frame", () => {
+		const cls = surfaceVariants({ material: "tray", padding: "md" }).root();
+		expect(cls).toContain("bg-muted/70");
+		expect(cls).toContain("rounded-2xl");
+		expect(cls).toContain("p-1");
+		expect(cls).not.toMatch(/\bp-4\b/);
+		expect(cls).not.toContain("bg-card");
+	});
+
+	test("a panel in a tray takes the xl corner", () => {
+		expect(surfaceVariants({ inTray: true }).root()).toContain("rounded-xl");
+		expect(surfaceVariants({ inTray: true }).root()).not.toContain("rounded-lg");
+	});
+
+	test("lists every material", () => {
+		expect(SURFACE_MATERIALS).toEqual(["flat", "etched", "tray"]);
+	});
+});
+
+describe("tray planes", () => {
+	// The tray paints its own muted fill, so what sits in it steps from nothing:
+	// a default card panel, not a secondary one on a muted ground.
+	test("a tray resets the plane so its panels resolve to the card fill", () => {
+		const through = resolveSurfacePlane({ parentPlane: "tertiary", variant: "default", material: "tray" });
+		expect(through).toBeNull();
+		expect(resolveSurfaceVariant({ parentPlane: through })).toBe("default");
+	});
+
+	test("other materials leave the plane alone", () => {
+		expect(resolveSurfacePlane({ parentPlane: null, variant: "secondary", material: "etched" })).toBe("secondary");
+	});
+});

package/src/components/surface/surface.variants.ts

@@ -5,6 +5,18 @@ export const SURFACE_VARIANTS = ["default", "secondary", "tertiary", "transparen
 
 export const SURFACE_PADDINGS = ["none", "sm", "md", "lg"] as const;
 
+/**
+ * What the surface is made of, orthogonal to which plane it fills.
+ *
+ * `flat` is the library default and draws nothing extra. `etched` sets a
+ * one-pixel highlight into the edge with a very soft drop — see the
+ * `--shadow-etched` tokens. `tray` is the muted frame that holds panels: a
+ * 2xl corner, 4pt of padding and a translucent muted fill, so the panels in it
+ * read as inset cards rather than as loose boxes on a page.
+ */
+export const SURFACE_MATERIALS = ["flat", "etched", "tray"] as const;
+
+export type SurfaceMaterial = (typeof SURFACE_MATERIALS)[number];
 export type SurfaceVariant = (typeof SURFACE_VARIANTS)[number];
 export type SurfacePadding = (typeof SURFACE_PADDINGS)[number];
 
@@ -88,10 +100,25 @@ export const surfaceVariants = tv({
 			md: { root: "p-4" },
 			lg: { root: "p-6" },
 		},
+		material: {
+			flat: {},
+			etched: { root: "shadow-etched dark:shadow-etched-dark" },
+			tray: {},
+		},
+		// A panel sitting in a tray: one corner step under the tray's own, so
+		// the gap between the two curves stays even round the edge.
+		inTray: { true: {}, false: {} },
 	},
+	compoundVariants: [
+		// Beats the padding axis, so a tray is `p-1` whatever `padding` says.
+		{ material: "tray", class: { root: "rounded-2xl border-transparent bg-muted/70 p-1" } },
+		{ inTray: true, class: { root: "rounded-xl" } },
+	],
 	defaultVariants: {
 		variant: "default",
 		padding: "md",
+		material: "flat",
+		inTray: false,
 	},
 });
 
@@ -123,11 +150,16 @@ export function resolveSurfaceVariant({
  * surface, which paints none — the plane it sits on itself.
  */
 export function resolveSurfacePlane({
+	material = "flat",
 	parentPlane,
 	variant,
 }: {
+	material?: SurfaceMaterial;
 	parentPlane: SurfacePlane | null;
 	variant: SurfaceVariant;
 }): SurfacePlane | null {
+	// A tray paints its own muted fill, so what it holds steps from no plane at
+	// all and resolves to the card fill rather than the next rung down.
+	if (material === "tray") return null;
 	return variant === "transparent" ? parentPlane : variant;
 }

package/src/components/text/AGENTS.md

@@ -1,9 +1,9 @@
 # Text
 
 The library's type scale, and the one component that reproduces React Native's
-own text inheritance through classNames. Compound root plus twelve presets:
+own text inheritance through classNames. Compound root plus thirteen presets:
 `Display`, `Title`, `Header`, `Subheader`, `Paragraph`, `Label`, `Caption`,
-`Overline`, and the four inline ones — `Strong`, `Emphasis`, `Link`, `Code`.
+`Overline`, `Kicker`, and the four inline ones — `Strong`, `Emphasis`, `Link`, `Code`.
 
 `import { Text } from "@delacour/react-native-ui/text";`
 
@@ -61,6 +61,12 @@ own text inheritance through classNames. Compound root plus twelve presets:
   so Tailwind v4's logical-property utilities resolve to a value RN rejects.
   `transform: "none"` emits `normal-case` rather than an empty string, so it can
   actually clear an `Overline`'s `uppercase`.
+- **`Kicker` is the mono, 10-point, 0.2em-tracked label — an opt-in sibling of
+  `Overline`, not a replacement.** Its size and tracking are the `--text-kicker`
+  and `--tracking-kicker` tokens in `tokens.css`, registered with
+  `tailwind-merge` as a pair (`KICKER_TOKEN`) so `text-kicker` is read as a
+  size and never as a colour. `font-mono` is deliberate: it labels, it does not
+  read as a sentence. Nothing in the default look uses it.
 - **A nested `Text.Code` cannot be padded.** A nested `<Text>` is laid out by the
   platform's text engine — an `NSAttributedString` run on iOS, a `Span` on
   Android — and both ignore padding, margin and border radius on an inner

package/src/components/text/text.tsx

@@ -142,6 +142,12 @@ function TextOverline(props: TextPresetProps): ReactElement {
 }
 TextOverline.displayName = "DelacourUI.Text.Overline";
 
+/** The tiny tracked mono label over a group, a screen or a field. */
+function TextKicker(props: TextPresetProps): ReactElement {
+	return <TextRoot variant="kicker" {...props} />;
+}
+TextKicker.displayName = "DelacourUI.Text.Kicker";
+
 /**
  * Inline emphasis by weight.
  *
@@ -238,6 +244,7 @@ export const Text = Object.assign(TextRoot, {
 	/** Supporting copy — 14pt on the muted token. */
 	Caption: TextCaption,
 	/** An eyebrow above a section — 12pt semibold, uppercase, muted. */
+	Kicker: TextKicker,
 	Overline: TextOverline,
 	/** Inline emphasis by weight. Inherits size and colour from the text around it. */
 	Strong: TextStrong,

package/src/components/text/text.variants.test.ts

@@ -17,7 +17,7 @@ import {
 } from "./text.variants";
 
 /** Tailwind's type scale, smallest first — position, so a test can say "a step down". */
-const TYPE_SCALE = ["text-xs", "text-sm", "text-base", "text-lg", "text-xl", "text-2xl", "text-3xl"];
+const TYPE_SCALE = ["text-kicker", "text-xs", "text-sm", "text-base", "text-lg", "text-xl", "text-2xl", "text-3xl"];
 
 /** The three alignment utilities, which share the `text-` prefix with sizes and colours. */
 const ALIGNMENTS = ["text-left", "text-center", "text-right"];
@@ -420,3 +420,26 @@ describe("TEXT_MAX_FONT_SIZE_MULTIPLIER", () => {
 		expect(TEXT_MAX_FONT_SIZE_MULTIPLIER).toBeGreaterThan(1);
 	});
 });
+
+describe("the kicker variant", () => {
+	const cls = textVariants({ variant: "kicker" });
+
+	test("is a ten-point uppercase mono label, tracked wide", () => {
+		expect(cls).toContain("font-mono");
+		expect(cls).toContain("text-kicker");
+		expect(cls).toContain("uppercase");
+		expect(cls).toContain("tracking-kicker");
+		expect(cls).toContain("text-muted-foreground");
+	});
+
+	test("is listed, and is not an inline variant", () => {
+		expect(TEXT_VARIANTS).toContain("kicker");
+		expect(isInlineTextVariant("kicker")).toBe(false);
+	});
+
+	test("survives resolveTextClass without losing its size to the base class", () => {
+		const resolved = resolveTextClass({ variant: "kicker" });
+		expect(resolved).toContain("text-kicker");
+		expect(resolved).not.toContain("text-base");
+	});
+});

package/src/components/text/text.variants.ts

@@ -18,6 +18,7 @@ export const TEXT_VARIANTS = [
 	"label",
 	"caption",
 	"overline",
+	"kicker",
 	"strong",
 	"emphasis",
 	"link",
@@ -136,6 +137,10 @@ export const textVariants = tv({
 			label: "font-medium text-sm text-foreground",
 			caption: "text-sm text-muted-foreground",
 			overline: "font-semibold text-muted-foreground text-xs uppercase tracking-wide",
+			// The tiny tracked mono label over a group or a screen. `font-mono`
+			// rather than `font-sans`, which is the point of it: it reads as a
+			// measurement, not a sentence. Tokens, not literals — see tokens.css.
+			kicker: "font-mono text-kicker text-muted-foreground uppercase tracking-kicker",
 			// The four below emit a delta and nothing else. See TEXT_INLINE_VARIANTS.
 			strong: "font-semibold",
 			emphasis: "italic",

package/src/components/textarea/AGENTS.md

@@ -84,3 +84,6 @@ A multiline text field, sized in rows. One component, no parts: it renders an
   either context and take its box or its corner, but a decorated or joined
   paragraph is not a control this library draws, and the height math assumes
   the box is the field's own.
+
+- **Takes `Input`'s `etched` variant** — the box is `Input`'s, so the third `INPUT_VARIANTS` value
+  reaches the textarea unchanged.

package/src/lib/cn.parity.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { extendTailwindMerge } from "tailwind-merge";
+import { type CustomClassGroupId, TW_MERGE_CONFIG } from "../styles/tokens";
+import { cn } from "./cn";
+
+/**
+ * `cn` against the tailwind-merge it replaced, on this library's own classes.
+ *
+ * `cn` promises tailwind-merge's output for every input; this holds it to that
+ * on the strings that matter here — every class literal in a `*.variants.ts`,
+ * merged pairwise with a caller-style override, through the same
+ * `TW_MERGE_CONFIG`. tailwind-merge stays installed as `tailwind-variants`'
+ * peer, which is what makes the reference available.
+ */
+const reference = extendTailwindMerge<CustomClassGroupId>(TW_MERGE_CONFIG);
+
+function variantFiles(dir: string): string[] {
+	return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) return variantFiles(path);
+		return entry.name.endsWith(".variants.ts") ? [path] : [];
+	});
+}
+
+const literals = [
+	...new Set(
+		variantFiles(join(import.meta.dir, "../components")).flatMap((file) =>
+			[...readFileSync(file, "utf8").matchAll(/"([a-z0-9!:[\]/.\-_% ]+)"/g)]
+				.map((match) => match[1] ?? "")
+				.filter((value) => value.includes("-"))
+		)
+	),
+];
+
+const OVERRIDES = [
+	"p-4",
+	"h-12",
+	"rounded-none",
+	"bg-destructive",
+	"text-sm",
+	"text-primary",
+	"opacity-50",
+	"h-button-sm",
+];
+
+describe("cn matches tailwind-merge on the library's classes", () => {
+	test("found a real corpus", () => {
+		expect(literals.length).toBeGreaterThan(100);
+	});
+
+	test("every literal alone", () => {
+		for (const value of literals) expect(cn(value)).toBe(reference(value));
+	});
+
+	test("every literal under a caller override", () => {
+		for (const value of literals) {
+			for (const override of OVERRIDES) expect(cn(value, override)).toBe(reference(value, override));
+		}
+	});
+});

package/src/lib/cn.ts

@@ -1,11 +1,16 @@
-import { type ClassValue, clsx } from "clsx";
-import { extendTailwindMerge } from "tailwind-merge";
-import { type CustomClassGroupId, TW_MERGE_CONFIG } from "../styles/tokens";
+import type { ClassValue } from "cn";
+import { createCn } from "cn/config";
+import { TW_MERGE_CONFIG } from "../styles/tokens";
 
 /**
- * tailwind-merge, taught the semantic size tokens from `tokens.css`.
+ * Class joining and conflict resolution, taught the semantic size tokens from `tokens.css`.
  *
- * Registering them is load-bearing rather than tidiness. tailwind-merge only
+ * Built on `cn` (shadcn-ui/cn), which replaces `clsx` + `tailwind-merge` with one
+ * engine: the same join semantics, the same merge output, and much cheaper on the
+ * repeated calls a render loop makes. `createCn` takes tailwind-merge's own
+ * `{ extend }` shape, so `TW_MERGE_CONFIG` is passed unchanged.
+ *
+ * Registering the tokens is load-bearing rather than tidiness. The merger only
  * treats two classes as conflicting when it recognises both as members of the
  * same group, and `button-md` is not a value it knows. Left unregistered,
  * `cn("h-button-md", "h-12")` returns *both* classes: they each resolve to a
@@ -15,7 +20,7 @@ import { type CustomClassGroupId, TW_MERGE_CONFIG } from "../styles/tokens";
  *
  * `tv()` needs the same treatment for its own merger — see `lib/tv.ts`.
  */
-const twMerge = extendTailwindMerge<CustomClassGroupId>(TW_MERGE_CONFIG);
+const merge = createCn(TW_MERGE_CONFIG);
 
 /**
  * Merges class names and resolves Tailwind conflicts so the last utility wins.
@@ -25,5 +30,5 @@ const twMerge = extendTailwindMerge<CustomClassGroupId>(TW_MERGE_CONFIG);
  * `className` through this before handing it to a component.
  */
 export function cn(...inputs: ClassValue[]): string {
-	return twMerge(clsx(inputs));
+	return merge(...inputs);
 }

package/src/styles/tokens.css

@@ -107,6 +107,39 @@
 	--spacing-chart-md: 220px;
 	--spacing-chart-lg: 280px;
 
+	/*
+	 * The kicker: the tiny uppercase mono label that sits over a group, a
+	 * screen or a field. Ten points at 0.2em tracking, named as a pair so
+	 * `Text variant="kicker"` and a hand-written `text-kicker tracking-kicker`
+	 * agree. Nothing reads it unless asked, so the default look is unchanged.
+	 */
+	--text-kicker: 10px;
+	--tracking-kicker: 0.2em;
+
+	/*
+	 * The etched material: a one-pixel highlight set into a surface's edge plus
+	 * a very soft drop. Light puts the highlight on the bottom edge as a
+	 * darkening, dark puts it on the top edge as a lightening, so a card reads
+	 * as lit from above in both. They are two tokens because one `shadow-*`
+	 * utility sets one `box-shadow` and a scheme flip needs `dark:`.
+	 *
+	 * `etched-primary` is the primary button's own: a white inset top edge at
+	 * 16% that is the same in both schemes, because the fill under it is the
+	 * dark one in light and invisible against the pale one in dark.
+	 *
+	 * `focus` is the three-point halo an etched field draws round its ring
+	 * border. A neutral alpha rather than the ring colour: `color-mix` inside a
+	 * `box-shadow` does not survive Uniwind's compile and draws nothing, and
+	 * the ring is a neutral in every base ramp anyway.
+	 *
+	 * Opt-in only: no default component reads any of these.
+	 */
+	--shadow-etched: inset 0 -1px 0 0 rgb(0 0 0 / 4%), 0 1px 2px 0 rgb(0 0 0 / 5%);
+	--shadow-etched-dark: inset 0 1px 0 0 rgb(255 255 255 / 6%), 0 1px 2px 0 rgb(0 0 0 / 30%);
+	--shadow-etched-primary: inset 0 1px 0 0 rgb(255 255 255 / 16%), 0 1px 2px 0 rgb(0 0 0 / 5%);
+	--shadow-focus: 0 0 0 3px rgb(0 0 0 / 10%);
+	--shadow-focus-dark: 0 0 0 3px rgb(255 255 255 / 14%);
+
 	/*
 	 * A floating action button's footprint — the circle's edge, and the
 	 * height of an extended one. A scale of its own rather than

package/src/styles/tokens.test.ts

@@ -6,11 +6,14 @@ import {
 	BUTTON_SIZE_TOKENS,
 	BUTTON_TEXT_TOKENS,
 	CHART_SIZE_TOKENS,
+	ETCHED_SHADOW_TOKENS,
 	FAB_SIZE_TOKENS,
 	ICON_SIZE_TOKENS,
 	INPUT_SIZE_TOKENS,
 	INPUT_TEXT_TOKENS,
+	KICKER_TOKEN,
 	SCREEN_SIZE_TOKENS,
+	TW_MERGE_CONFIG,
 } from "./tokens";
 
 const CSS = readFileSync(join(import.meta.dirname, "tokens.css"), "utf-8");
@@ -182,6 +185,37 @@ describe("the input scale", () => {
 	});
 });
 
+describe("the etched material", () => {
+	test("declares every shadow the registry names, and no other", () => {
+		const declared = [...CSS.matchAll(/--shadow-([\w-]+):/g)].map((match) => match[1]).sort();
+		expect(declared).toEqual([...ETCHED_SHADOW_TOKENS].sort());
+	});
+
+	// An inset layer is what makes it a highlight rather than a drop shadow, and
+	// the soft outer layer is what lifts the edge off the page.
+	test("light and dark edges sit on opposite sides of the surface", () => {
+		expect(CSS).toMatch(/--shadow-etched:\s*inset 0 -1px/);
+		expect(CSS).toMatch(/--shadow-etched-dark:\s*inset 0 1px/);
+		expect(CSS).toMatch(/--shadow-etched-primary:\s*inset 0 1px 0 0 rgb\(255 255 255 \/ 16%\)/);
+	});
+
+	test("registers its shadows so a caller's shadow-* can replace them", () => {
+		expect(TW_MERGE_CONFIG.extend.theme.shadow).toEqual([...ETCHED_SHADOW_TOKENS]);
+	});
+});
+
+describe("the kicker type style", () => {
+	test("is ten points, tracked at 0.2em", () => {
+		expect(px("text-kicker")).toBe(10);
+		expect(CSS).toMatch(/--tracking-kicker:\s*0\.2em;/);
+	});
+
+	test("registers both tokens so text-kicker is read as a size, not a colour", () => {
+		expect(TW_MERGE_CONFIG.extend.theme.text).toContain(KICKER_TOKEN);
+		expect(TW_MERGE_CONFIG.extend.theme.tracking).toEqual([KICKER_TOKEN]);
+	});
+});
+
 describe("the fab scale", () => {
 	test("ascends in the order the registry lists it", () => {
 		const values = FAB_SIZE_TOKENS.map((token) => px(`spacing-${token}`));

package/src/styles/tokens.ts

@@ -82,6 +82,12 @@ export const FAB_SIZE_TOKENS = ["fab-sm", "fab-md", "fab-lg"] as const;
  * `borderCurve`. Unregistered, tailwind-merge reads it as a border *colour*,
  * and `border-continuous border-border` loses one of the two.
  */
+/** Names of the shadows the etched material declares in `tokens.css`. */
+export const ETCHED_SHADOW_TOKENS = ["etched", "etched-dark", "etched-primary", "focus", "focus-dark"] as const;
+
+/** The size and tracking token behind `Text variant="kicker"`; one name for both. */
+export const KICKER_TOKEN = "kicker";
+
 export const TW_MERGE_CONFIG = {
 	extend: {
 		classGroups: {
@@ -97,7 +103,9 @@ export const TW_MERGE_CONFIG = {
 				...INPUT_SIZE_TOKENS,
 				...SCREEN_SIZE_TOKENS,
 			],
-			text: [...BUTTON_TEXT_TOKENS, ...INPUT_TEXT_TOKENS],
+			shadow: [...ETCHED_SHADOW_TOKENS],
+			text: [...BUTTON_TEXT_TOKENS, ...INPUT_TEXT_TOKENS, KICKER_TOKEN],
+			tracking: [KICKER_TOKEN],
 		},
 	},
 } as const;