@delacour/react-native-ui 0.1.0-alpha.20260925064136 → 0.1.0-alpha.20260925064429

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20260925064136",
+	"version": "0.1.0-alpha.20260925064429",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -39,6 +39,7 @@
 		"./badge": "./src/components/badge/index.ts",
 		"./bottom-sheet": "./src/components/bottom-sheet/index.ts",
 		"./button": "./src/components/button/index.ts",
+		"./card": "./src/components/card/index.ts",
 		"./chart": "./src/components/chart/index.ts",
 		"./checkbox": "./src/components/checkbox/index.ts",
 		"./chip": "./src/components/chip/index.ts",
@@ -95,7 +96,7 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-charts": "0.1.0-alpha.20260925064136",
+		"@delacour/react-native-charts": "0.1.0-alpha.20260925064429",
 		"@gorhom/bottom-sheet": "^5.2.8",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",

package/src/components/card/AGENTS.md

@@ -0,0 +1,88 @@
+# Card
+
+A content surface with a header, a body and a footer, built on
+[`Surface`](../surface/AGENTS.md). Compound root plus six parts: `Header`,
+`Title`, `Description`, `Action`, `Content`, `Footer`.
+
+`import { Card } from "@delacour/react-native-ui/card";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/card` |
+| `card.tsx` | Root + the `Object.assign` compound surface |
+| `card-header.tsx` | `Card.Header`, and the bare-text wrap it owns |
+| `card-title.tsx` | `Card.Title` |
+| `card-description.tsx` | `Card.Description` |
+| `card-action.tsx` | `Card.Action` |
+| `card-content.tsx` | `Card.Content` |
+| `card-footer.tsx` | `Card.Footer` |
+| `card.context.tsx` | `CardProvider`, `useCard()`, `useCardContext()`, `useCardPart()` |
+| `card.types.ts` | Prop types shared by two or more parts |
+| `card.variants.ts` | The slotted `tv()`, `resolveCardFooterFill`, `splitCardHeaderChildren` — no RN imports |
+| `card.variants.test.ts` | |
+
+## Design
+
+- **The surface is `Surface`'s; the card adds only the rhythm between its
+  parts.** Fill, hairline, corner and clip all come from `Surface` at
+  `padding="none"`, so `variant` is `Surface`'s four fills with the same
+  nesting rule — a card that names none is the hairlined `default` on a screen
+  and steps to the next fill inside another surface. A card is not a second
+  definition of what a card-shaped surface looks like.
+- **The root resolves the fill itself as well as passing it down.** The parts
+  need the plane the card landed on — the title's colour and a band footer's
+  fill key off it — and `Surface` does not publish a prop it was never given.
+  So `Card` runs the same two pure resolvers and hands `Surface` the explicit
+  result; the two cannot disagree, because it is one function called twice.
+- **Padding lives on the parts, not the root.** The root carries `pt`/`pb`
+  and a `gap` of the same step; `Header`, `Content` and `Footer` carry that step as
+  `px`. An image written straight into the card therefore reaches both side
+  edges with nothing to undo, and `className="pt-0"` on the card bleeds it to
+  the top. Content that must not be clipped does not belong in a card: the root
+  is `padding="none"`, which is `Surface`'s one clipping step.
+- **The root's vertical padding is `pt`/`pb`, never `py`.** The root is the
+  surface's view, which carries `p-0` at `padding="none"`, and Uniwind resolves
+  that shorthand over a `py-*` on the same view — the first build on a device
+  drew the title flush against the top hairline. The longhands win, and a test
+  forbids `py-` on the root so it cannot come back.
+- **Sizes**: `sm`, `md`, `lg` — insets of 3, 4 and 6, which are `Surface`'s own
+  padding steps, so a card and a surface side by side at one size hold their
+  content at one distance from the edge. Size is one axis for five numbers —
+  vertical padding, gap, horizontal inset, title scale, description scale —
+  and the test pins the three insets to each other rather than to numbers.
+- **The title is on its plane's foreground token.** `text-card-foreground` on
+  the card fill, `text-secondary-foreground` on a secondary card, and
+  `text-foreground` for a transparent card on the page. Written out per plane
+  in the `tv()`, because Tailwind's scanner cannot see a class built at
+  runtime. The description is `muted-foreground` everywhere.
+- **`Card.Title` is announced as a header**, so a screen reader's rotor can
+  step card to card through a list of them.
+- **`Card.Action` is lifted out of the header's text column, wherever it is
+  written.** React Native has no grid to place a child by type, so the header
+  walks its children with `splitCardHeaderChildren` and renders the text column
+  as `flex-1` with the actions after it. The title wraps in the width an action
+  leaves instead of pushing it off the edge. The helper takes its predicate as
+  an argument so it stays in `card.variants.ts`, free of the part and of React
+  Native, and reachable from `bun test`.
+- **Bare text in a header is its title.** A raw string inside a `View` is a
+  red box, and a header's text is its heading — the same wrap, for the same
+  reason, as [`ListGroup.Item`](../list-group/AGENTS.md).
+- **Footer variants**: `default`, a wrapping row of actions; `band`, a strip
+  set into the card — `border-t`, the next fill down, and the card's bottom
+  corners. The band pulls itself down over the root's bottom padding with a
+  `-mb-*` of exactly that step and restates it as `py-*`, so it meets the edge
+  and the root's clip gives it the corners. That only works as the last child,
+  which the doc comment says.
+- **A band's fill is a step on the ladder, not a colour.**
+  `resolveCardFooterFill` is `resolveSurfaceVariant` for the card's plane — the
+  same step a surface nested in the card would take — so a band never matches
+  the card it sits in, at any depth. A transparent card on the page has no
+  plane, and its band takes the card fill.
+- **No interaction on the card.** A card is layout. A card that selects or
+  navigates is a `Pressable` around it — `<Pressable asChild>` or a wrapper —
+  which keeps `feedback`, `haptic` and the accessibility role at the call site
+  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.

package/src/components/card/card-action.tsx

@@ -0,0 +1,16 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useCardPart } from "./card.context";
+import type { CardSlotProps } from "./card.types";
+import { cardVariants } from "./card.variants";
+
+/**
+ * A control pinned to the header's top-right corner — a menu button, a badge, a
+ * link. `Card.Header` lifts it out of the text column wherever it is written, so
+ * the title and description keep the width it leaves.
+ */
+export function CardAction({ className, ...props }: CardSlotProps): ReactElement {
+	const { size } = useCardPart("Card.Action");
+	return <View className={cardVariants({ size }).action({ className })} {...props} />;
+}
+CardAction.displayName = "DelacourUI.Card.Action";

package/src/components/card/card-content.tsx

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useCardPart } from "./card.context";
+import type { CardSlotProps } from "./card.types";
+import { cardVariants } from "./card.variants";
+
+/** The card's body, inset to line up with the header and footer and spaced by the card's size. */
+export function CardContent({ className, ...props }: CardSlotProps): ReactElement {
+	const { size } = useCardPart("Card.Content");
+	return <View className={cardVariants({ size }).content({ className })} {...props} />;
+}
+CardContent.displayName = "DelacourUI.Card.Content";

package/src/components/card/card-description.tsx

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useCardPart } from "./card.context";
+import type { CardTextProps } from "./card.types";
+import { cardVariants } from "./card.variants";
+
+/** The muted supporting line under the title, a step down the type scale from it. */
+export function CardDescription({ className, ...props }: CardTextProps): ReactElement {
+	const { size } = useCardPart("Card.Description");
+	return <Text className={cardVariants({ size }).description({ className })} {...props} />;
+}
+CardDescription.displayName = "DelacourUI.Card.Description";

package/src/components/card/card-footer.tsx

@@ -0,0 +1,30 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useCardPart } from "./card.context";
+import type { CardSlotProps } from "./card.types";
+import { type CardFooterVariant, cardVariants, resolveCardFooterFill } from "./card.variants";
+
+export type CardFooterProps = CardSlotProps & {
+	/**
+	 * `default` is a row of actions under the content. `band` sets it into the
+	 * card as a strip of its own — a rule across the top, the next fill down, and
+	 * the card's bottom corners — for a footer that is what someone does with the
+	 * card rather than more of what it says.
+	 */
+	variant?: CardFooterVariant;
+};
+
+/**
+ * The card's last row — its actions, or a status line.
+ *
+ * A `band` footer steps its fill from the card's own plane rather than naming a
+ * colour, so it stays a step apart from the card however deep it is nested.
+ * It should be the card's last child: it pulls itself down over the card's
+ * bottom padding to meet the edge.
+ */
+export function CardFooter({ variant = "default", className, ...props }: CardFooterProps): ReactElement {
+	const { size, plane } = useCardPart("Card.Footer");
+	const slots = cardVariants({ footer: variant, footerFill: resolveCardFooterFill(plane), size });
+	return <View className={slots.footer({ className })} {...props} />;
+}
+CardFooter.displayName = "DelacourUI.Card.Footer";

package/src/components/card/card-header.tsx

@@ -0,0 +1,45 @@
+import { isValidElement, type ReactElement, type ReactNode } from "react";
+import { View } from "react-native";
+import { useCardPart } from "./card.context";
+import type { CardSlotProps } from "./card.types";
+import { cardVariants, splitCardHeaderChildren } from "./card.variants";
+import { CardAction } from "./card-action";
+import { CardTitle } from "./card-title";
+
+function isCardAction(node: ReactNode): boolean {
+	return isValidElement(node) && node.type === CardAction;
+}
+
+/**
+ * Wraps a bare string or number in a `Card.Title`. A raw string inside a `View`
+ * is a red box in React Native, and a header's bare text is its title.
+ */
+function wrapBareText(node: ReactNode, index: number): ReactNode {
+	return typeof node === "string" || typeof node === "number" ? (
+		<CardTitle key={`title-${index}`}>{node}</CardTitle>
+	) : (
+		node
+	);
+}
+
+/**
+ * The card's opening block: a title and description stacked on the left, and
+ * any `Card.Action` pinned to the top right.
+ *
+ * The header lifts every action out of the column wherever it is written, so
+ * the order of children does not matter and the text wraps in the width the
+ * action leaves. Bare text becomes a title.
+ */
+export function CardHeader({ className, children, ...props }: CardSlotProps): ReactElement {
+	const { size } = useCardPart("Card.Header");
+	const slots = cardVariants({ size });
+	const { text, actions } = splitCardHeaderChildren(children, isCardAction);
+
+	return (
+		<View className={slots.header({ className })} {...props}>
+			<View className={slots.headerText()}>{text.map(wrapBareText)}</View>
+			{actions}
+		</View>
+	);
+}
+CardHeader.displayName = "DelacourUI.Card.Header";

package/src/components/card/card-title.tsx

@@ -0,0 +1,25 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useCardPart } from "./card.context";
+import type { CardTextProps } from "./card.types";
+import { cardVariants } from "./card.variants";
+
+/**
+ * The card's heading.
+ *
+ * Carries its own colour — the foreground token of the plane the card resolved
+ * to — and its own step on the type scale, read from the card's context: a
+ * React Native `View` does not cascade colour to a `Text` descendant. Announced
+ * as a header, so a screen reader's rotor stops on each card in a list.
+ */
+export function CardTitle({ className, ...props }: CardTextProps): ReactElement {
+	const { size, plane } = useCardPart("Card.Title");
+	return (
+		<Text
+			accessibilityRole="header"
+			className={cardVariants({ plane: plane ?? "none", size }).title({ className })}
+			{...props}
+		/>
+	);
+}
+CardTitle.displayName = "DelacourUI.Card.Title";

package/src/components/card/card.context.tsx

@@ -0,0 +1,64 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { SurfacePlane, SurfaceVariant } from "../surface/surface.variants";
+import type { CardSize } from "./card.variants";
+
+export type CardContextValue = {
+	/** Size of the card — the padding, the gaps and the title and description scale. */
+	size: CardSize;
+	/** The fill the card resolved to — explicit, or stepped from the surface it sits in. */
+	variant: SurfaceVariant;
+	/**
+	 * The fill the card's content sits on. The same as `variant` unless that is
+	 * `transparent`, which passes the plane beneath it through — `null` on the page.
+	 */
+	plane: SurfacePlane | null;
+};
+
+const CardContext = createContext<CardContextValue | null>(null);
+
+/**
+ * Supplies the enclosing card's size and fill to its subtree.
+ *
+ * Lives in its own module, importing nothing but types, so a part the card
+ * renders can read it without importing `./card` and closing a cycle through
+ * `card.tsx`. See AGENTS.md rule 3.
+ */
+export function CardProvider({ value, children }: { value: CardContextValue; children: ReactNode }): ReactElement {
+	return <CardContext value={value}>{children}</CardContext>;
+}
+CardProvider.displayName = "DelacourUI.Card.Provider";
+
+/** The enclosing card's context, or null outside a `<Card>`. */
+export function useCardContext(): CardContextValue | null {
+	return use(CardContext);
+}
+
+/**
+ * Reads the enclosing card's size and fill.
+ *
+ * Lets a custom part match the card — the same inset, a colour that reads on
+ * its plane — without the card passing props down. Throws outside a `<Card>`;
+ * use {@link useCardContext} where the enclosing card is optional.
+ */
+export function useCard(): CardContextValue {
+	const context = useCardContext();
+	if (!context) {
+		throw new Error("useCard must be called inside a <Card>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing card's context, for a compound part that cannot work without one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`. A caller outside the
+ * library wants {@link useCard}, whose error message names the hook rather than
+ * a part.
+ */
+export function useCardPart(component: string): CardContextValue {
+	const context = useCardContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Card>.`);
+	}
+	return context;
+}

package/src/components/card/card.tsx

@@ -0,0 +1,94 @@
+import { type ReactElement, useMemo } from "react";
+import { Surface, type SurfaceProps, useSurfaceContext } from "../surface";
+import { resolveSurfacePlane, resolveSurfaceVariant } from "../surface/surface.variants";
+import { type CardContextValue, CardProvider } from "./card.context";
+import { type CardSize, cardVariants } from "./card.variants";
+import { CardAction } from "./card-action";
+import { CardContent } from "./card-content";
+import { CardDescription } from "./card-description";
+import { CardFooter } from "./card-footer";
+import { CardHeader } from "./card-header";
+import { CardTitle } from "./card-title";
+
+export type CardProps = Omit<SurfaceProps, "padding"> & {
+	/** The inset, the gaps between the parts, and the title and description scale. */
+	size?: CardSize;
+};
+
+function CardRoot({ variant, 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 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}>
+				{children}
+			</Surface>
+		</CardProvider>
+	);
+}
+
+/**
+ * A content surface with a header, a body and a footer.
+ *
+ * Built on `Surface`, so it takes the same four fills and steps the same way:
+ * a card that names no variant is the hairlined `default` at the top of a
+ * screen and the next fill down inside another surface. The root is
+ * `padding="none"`, which clips — the padding lives on the parts, so an image
+ * placed straight in the card reaches its side edges, and `className="pt-0"`
+ * bleeds it to the top.
+ *
+ * `size` reaches every part through context, so the header, the body and the
+ * footer line up on one inset and the title picks its own scale and colour —
+ * a React Native `View` cannot cascade either to a `Text`.
+ *
+ * @example
+ * <Card>
+ *   <Card.Header>
+ *     <Card.Title>Monthly report</Card.Title>
+ *     <Card.Description>Revenue and retention for October.</Card.Description>
+ *     <Card.Action>
+ *       <Badge>New</Badge>
+ *     </Card.Action>
+ *   </Card.Header>
+ *   <Card.Content>
+ *     <Text.Title>$48,120</Text.Title>
+ *   </Card.Content>
+ *   <Card.Footer>
+ *     <Button size="sm" variant="outline">Export</Button>
+ *     <Button size="sm">Open</Button>
+ *   </Card.Footer>
+ * </Card>
+ *
+ * @example
+ * <Card className="pt-0">
+ *   <Image className="h-40 w-full" source={cover} />
+ *   <Card.Header>
+ *     <Card.Title>Lake Tekapo</Card.Title>
+ *   </Card.Header>
+ *   <Card.Footer variant="band">
+ *     <Button size="sm">Book</Button>
+ *   </Card.Footer>
+ * </Card>
+ */
+export const Card = Object.assign(CardRoot, {
+	/** The opening block. Stacks a title and description, and pins any `Card.Action` to the top right. */
+	Header: CardHeader,
+	/** The card's heading, on its plane's foreground token. Announced as a header. */
+	Title: CardTitle,
+	/** The muted supporting line under the title. */
+	Description: CardDescription,
+	/** A control pinned to the header's top-right corner, wherever in the header it is written. */
+	Action: CardAction,
+	/** The card's body, inset to line up with the header and footer. */
+	Content: CardContent,
+	/** The last row — a row of actions, or with `variant="band"` a strip set into the card. */
+	Footer: CardFooter,
+	displayName: "DelacourUI.Card",
+});

package/src/components/card/card.types.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+import type { ViewProps } from "react-native";
+import type { TextPresetProps } from "../text";
+
+/**
+ * The shape of a card's layout parts — `Header`, `Action` and `Content`, and
+ * extended by `Footer` — so it lives in a leaf rather than in one of them
+ * arbitrarily.
+ */
+export type CardSlotProps = ViewProps & { className?: string; children?: ReactNode };
+
+/** The shape of a card's two text parts, `Title` and `Description`. */
+export type CardTextProps = TextPresetProps;

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

@@ -0,0 +1,240 @@
+import { describe, expect, test } from "bun:test";
+import { createElement, Fragment, type ReactNode } from "react";
+import { SURFACE_FILLED_VARIANTS } from "../surface/surface.variants";
+import {
+	CARD_FOOTER_VARIANTS,
+	CARD_PLANES,
+	CARD_SIZES,
+	cardVariants,
+	resolveCardFooterFill,
+	splitCardHeaderChildren,
+} from "./card.variants";
+
+/** Every slot the variant function can produce, one call per combination. */
+function everyCombination(): ReturnType<typeof cardVariants>[] {
+	return CARD_SIZES.flatMap((size) =>
+		CARD_PLANES.flatMap((plane) =>
+			CARD_FOOTER_VARIANTS.flatMap((footer) =>
+				SURFACE_FILLED_VARIANTS.map((footerFill) => cardVariants({ footer, footerFill, plane, size }))
+			)
+		)
+	);
+}
+
+/** The numeric step of the first `${prefix}-N` utility in a class string. */
+function step(cls: string, prefix: string): string | undefined {
+	return cls.match(new RegExp(`(?:^|\\s)${prefix}-(\\d+(?:\\.5)?)(?:\\s|$)`))?.[1];
+}
+
+describe("cardVariants root slot", () => {
+	// The padding lives on the parts, so the root carries only the vertical
+	// rhythm between them — horizontal padding here would stop a bled image
+	// reaching the card's side edges.
+	test("carries no horizontal padding at any size", () => {
+		for (const size of CARD_SIZES) {
+			const cls = cardVariants({ size }).root();
+			expect(cls).not.toMatch(/(^|\s)(p|px|pl|pr)-/);
+		}
+	});
+
+	test("spaces its parts by the same step it pads its top and bottom", () => {
+		for (const size of CARD_SIZES) {
+			const cls = cardVariants({ size }).root();
+			expect(step(cls, "pt")).toBeDefined();
+			expect(step(cls, "pb")).toBe(step(cls, "pt"));
+			expect(step(cls, "gap")).toBe(step(cls, "pt"));
+		}
+	});
+
+	// The card sits on a `padding="none"` surface, whose root carries `p-0`.
+	// Uniwind resolves that shorthand over a `py-*` on the same view, so the
+	// card's vertical padding vanished on a device; the longhands hold.
+	test("pads top and bottom with longhands, never the py shorthand", () => {
+		for (const size of CARD_SIZES) {
+			expect(cardVariants({ size }).root()).not.toMatch(/(^|\s)py-/);
+		}
+	});
+
+	// Rule 1: a React Native View does not cascade colour to a Text descendant.
+	test("carries no text treatment on the root, header, content or footer", () => {
+		for (const slots of everyCombination()) {
+			for (const cls of [slots.root(), slots.header(), slots.content(), slots.footer()]) {
+				expect(cls).not.toMatch(/(^|\s)text-/);
+			}
+		}
+	});
+
+	test("merges an incoming className last", () => {
+		expect(cardVariants().root({ className: "pt-0" })).toContain("pt-0");
+		expect(cardVariants().root({ className: "gap-8" })).not.toMatch(/(^|\s)gap-4(\s|$)/);
+	});
+});
+
+describe("cardVariants size", () => {
+	test("defaults to md", () => {
+		expect(cardVariants().root()).toBe(cardVariants({ size: "md" }).root());
+		expect(cardVariants().title()).toBe(cardVariants({ size: "md" }).title());
+	});
+
+	test("matches Surface's padding steps: 3, 4 and 6", () => {
+		expect(step(cardVariants({ size: "sm" }).root(), "pt")).toBe("3");
+		expect(step(cardVariants({ size: "md" }).root(), "pt")).toBe("4");
+		expect(step(cardVariants({ size: "lg" }).root(), "pt")).toBe("6");
+	});
+
+	// The header, the body and the footer have to line up on one inset, or the
+	// title sits a few points off the button beneath it.
+	test("header, content and footer share one horizontal inset, equal to the vertical one", () => {
+		for (const size of CARD_SIZES) {
+			const slots = cardVariants({ size });
+			const inset = step(slots.root(), "pt");
+			expect(step(slots.header(), "px")).toBe(inset);
+			expect(step(slots.content(), "px")).toBe(inset);
+			expect(step(slots.footer(), "px")).toBe(inset);
+		}
+	});
+
+	test("steps the title and description type scale with the size", () => {
+		expect(cardVariants({ size: "sm" }).title()).toContain("text-sm");
+		expect(cardVariants({ size: "md" }).title()).toContain("text-base");
+		expect(cardVariants({ size: "lg" }).title()).toContain("text-lg");
+		expect(cardVariants({ size: "sm" }).description()).toContain("text-xs");
+		expect(cardVariants({ size: "md" }).description()).toContain("text-sm");
+		expect(cardVariants({ size: "lg" }).description()).toContain("text-base");
+	});
+
+	test("gives every size a distinct root", () => {
+		const seen = new Set(CARD_SIZES.map((size) => cardVariants({ size }).root()));
+		expect(seen.size).toBe(CARD_SIZES.length);
+	});
+});
+
+describe("cardVariants title and description", () => {
+	test("the title is the X-foreground token of the plane it sits on", () => {
+		expect(cardVariants({ plane: "default" }).title()).toContain("text-card-foreground");
+		expect(cardVariants({ plane: "secondary" }).title()).toContain("text-secondary-foreground");
+		expect(cardVariants({ plane: "tertiary" }).title()).toContain("text-tertiary-foreground");
+		expect(cardVariants({ plane: "none" }).title()).toContain("text-foreground");
+	});
+
+	test("the title is semibold at every size", () => {
+		for (const size of CARD_SIZES) {
+			expect(cardVariants({ size }).title()).toContain("font-semibold");
+		}
+	});
+
+	test("the description sits on the muted token on every plane", () => {
+		for (const plane of CARD_PLANES) {
+			expect(cardVariants({ plane }).description()).toContain("text-muted-foreground");
+		}
+	});
+
+	// Two colour classes on one Text and tailwind-merge keeps only the last —
+	// which would be a page colour, not the plane's.
+	test("the title carries exactly one text colour", () => {
+		for (const slots of everyCombination()) {
+			const colours = slots
+				.title()
+				.split(/\s+/)
+				.filter((name) => /^text-(card|secondary|tertiary|foreground|muted)/.test(name));
+			expect(colours).toHaveLength(1);
+		}
+	});
+});
+
+describe("cardVariants header", () => {
+	test("lays the text column and the action out in a row", () => {
+		const slots = cardVariants();
+		expect(slots.header()).toContain("flex-row");
+		expect(slots.headerText()).toContain("flex-1");
+		expect(slots.action()).toContain("shrink-0");
+	});
+});
+
+describe("cardVariants footer", () => {
+	test("defaults to the plain row of actions", () => {
+		expect(cardVariants().footer()).toBe(cardVariants({ footer: "default" }).footer());
+		expect(cardVariants().footer()).toContain("flex-row");
+		expect(cardVariants().footer()).not.toContain("border-t");
+	});
+
+	test("a band draws a rule across its top and a fill of its own", () => {
+		for (const footerFill of SURFACE_FILLED_VARIANTS) {
+			const cls = cardVariants({ footer: "band", footerFill }).footer();
+			expect(cls).toContain("border-t");
+			expect(cls).toContain("border-border");
+			expect(cls).toMatch(/(^|\s)bg-/);
+		}
+	});
+
+	test("only a band paints a fill", () => {
+		for (const footerFill of SURFACE_FILLED_VARIANTS) {
+			expect(cardVariants({ footer: "default", footerFill }).footer()).not.toMatch(/(^|\s)bg-/);
+		}
+	});
+
+	test("maps each band fill to its surface token", () => {
+		expect(cardVariants({ footer: "band", footerFill: "default" }).footer()).toContain("bg-card");
+		expect(cardVariants({ footer: "band", footerFill: "secondary" }).footer()).toContain("bg-secondary");
+		expect(cardVariants({ footer: "band", footerFill: "tertiary" }).footer()).toContain("bg-tertiary");
+	});
+
+	// A band is set INTO the card: it pulls down over the root's bottom padding
+	// by exactly that padding, and restates it inside, so it meets the card's
+	// bottom edge and its own content keeps the same breathing room.
+	test("a band cancels the root's bottom padding and restates it inside", () => {
+		for (const size of CARD_SIZES) {
+			const inset = step(cardVariants({ size }).root(), "pb");
+			const cls = cardVariants({ footer: "band", size }).footer();
+			expect(cls).toMatch(new RegExp(`(^|\\s)-mb-${inset?.replace(".", "\\.")}(\\s|$)`));
+			expect(step(cls, "py")).toBe(inset);
+		}
+	});
+});
+
+describe("resolveCardFooterFill", () => {
+	test("a band is a step from the card's own fill, never the same one", () => {
+		for (const plane of SURFACE_FILLED_VARIANTS) {
+			expect(resolveCardFooterFill(plane)).not.toBe(plane);
+		}
+	});
+
+	test("a card on the default fill gets a secondary band", () => {
+		expect(resolveCardFooterFill("default")).toBe("secondary");
+	});
+
+	// A transparent card on the page paints nothing, so its band steps from the
+	// page itself — the card fill, a step above it.
+	test("a card with no plane of its own gets a default band", () => {
+		expect(resolveCardFooterFill(null)).toBe("default");
+	});
+});
+
+describe("splitCardHeaderChildren", () => {
+	function Action(): null {
+		return null;
+	}
+	const isAction = (node: ReactNode): boolean =>
+		typeof node === "object" && node !== null && "type" in node && node.type === Action;
+
+	test("puts everything in the text column when there is no action", () => {
+		const { text, actions } = splitCardHeaderChildren(["Title", createElement(Fragment, null, "x")], isAction);
+		expect(text).toHaveLength(2);
+		expect(actions).toHaveLength(0);
+	});
+
+	test("lifts every action out of the text column, keeping order", () => {
+		const first = createElement(Action, { key: "a" });
+		const second = createElement(Action, { key: "b" });
+		const { text, actions } = splitCardHeaderChildren([first, "Title", second, "Description"], isAction);
+		expect(text).toEqual(["Title", "Description"]);
+		expect(actions).toHaveLength(2);
+	});
+
+	// A conditional action leaves `false` behind; it must not count as text.
+	test("drops the nulls and booleans a conditional child leaves behind", () => {
+		const { text, actions } = splitCardHeaderChildren(["Title", false, null, undefined], isAction);
+		expect(text).toEqual(["Title"]);
+		expect(actions).toHaveLength(0);
+	});
+});

package/src/components/card/card.variants.ts

@@ -0,0 +1,177 @@
+import { Children, type ReactNode } from "react";
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import { resolveSurfaceVariant, type SurfacePlane } from "../surface/surface.variants";
+
+export const CARD_SIZES = ["sm", "md", "lg"] as const;
+
+/** `default` is a row of actions; `band` sets the footer into the card as a strip of its own. */
+export const CARD_FOOTER_VARIANTS = ["default", "band"] as const;
+
+/**
+ * The planes a card's title can sit on: the three surface fills, plus `none`
+ * for a transparent card on the page, which has no fill of its own.
+ */
+export const CARD_PLANES = ["default", "secondary", "tertiary", "none"] as const;
+
+export type CardSize = (typeof CARD_SIZES)[number];
+export type CardFooterVariant = (typeof CARD_FOOTER_VARIANTS)[number];
+export type CardPlane = (typeof CARD_PLANES)[number];
+
+/**
+ * Styling for every part of a card.
+ *
+ * The card's own surface — fill, hairline, corner, clip — is `Surface`'s, at
+ * `padding="none"`. What this adds is the rhythm between the parts, and it
+ * puts the padding on the PARTS rather than on the root. The root holds only
+ * `pt`/`pb` and a `gap` of the same step; the header, content and footer each
+ * carry the same step as `px`. So an image placed straight in the card reaches
+ * both side edges with nothing to undo, and `className="pt-0"` on the card is
+ * all it takes to bleed one to the top as well.
+ *
+ * `pt`/`pb` rather than `py`, and that is load-bearing: the root is also the
+ * surface's, which carries `p-0` at `padding="none"`, and Uniwind resolves that
+ * shorthand over a `py-*` on the same view. The card rendered with no vertical
+ * padding at all until the longhands replaced it.
+ *
+ * Size is one axis for five numbers — the vertical padding, the gap, the
+ * horizontal inset and the title and description type scale — and the steps
+ * are Surface's own `sm`/`md`/`lg` (3, 4, 6), so a card and a surface beside
+ * it at the same size hold their content at the same distance from the edge.
+ *
+ * The title colour is keyed on `plane`, the fill the card resolved to, so a
+ * card nested in another reads `text-secondary-foreground` on the secondary
+ * fill rather than the card's token on something else. The classes are written
+ * out per plane because Tailwind's scanner cannot see a `text-${token}` built at
+ * runtime.
+ *
+ * A `band` footer is set INTO the card: `-mb-*` pulls it down over the root's
+ * bottom padding by exactly that padding and `py-*` restates it inside, so it
+ * meets the card's bottom edge — the root clips, so it takes the card's own
+ * corners — while its content keeps the same breathing room. Its fill is the
+ * next rung of the surface ladder from the card's, see
+ * {@link resolveCardFooterFill}.
+ *
+ * The root, header, content and footer carry no `text-*` (rule 1): a `View`
+ * does not cascade colour to a `Text`, so the tokens live on the title and
+ * description slots.
+ *
+ * Free of React Native imports so it stays unit-testable — `bun test` cannot
+ * parse React Native's Flow-typed source. See AGENTS.md.
+ */
+export const cardVariants = tv({
+	slots: {
+		root: "",
+		header: "flex-row items-start gap-3",
+		/** The column holding the title and description, beside any action. */
+		headerText: "flex-1",
+		action: "shrink-0 flex-row items-center self-start",
+		title: "font-semibold",
+		description: "text-muted-foreground",
+		content: "",
+		footer: "flex-row flex-wrap items-center gap-2",
+	},
+	variants: {
+		size: {
+			sm: {
+				root: "gap-3 pt-3 pb-3",
+				header: "px-3",
+				headerText: "gap-0.5",
+				content: "gap-2 px-3",
+				footer: "px-3",
+				title: "text-sm",
+				description: "text-xs",
+			},
+			md: {
+				root: "gap-4 pt-4 pb-4",
+				header: "px-4",
+				headerText: "gap-1",
+				content: "gap-3 px-4",
+				footer: "px-4",
+				title: "text-base",
+				description: "text-sm",
+			},
+			lg: {
+				root: "gap-6 pt-6 pb-6",
+				header: "px-6",
+				headerText: "gap-1.5",
+				content: "gap-4 px-6",
+				footer: "px-6",
+				title: "text-lg",
+				description: "text-base",
+			},
+		},
+		plane: {
+			default: { title: "text-card-foreground" },
+			secondary: { title: "text-secondary-foreground" },
+			tertiary: { title: "text-tertiary-foreground" },
+			none: { title: "text-foreground" },
+		},
+		footer: {
+			default: {},
+			band: { footer: "border-t border-border" },
+		},
+		// Read only by a band; the plain footer paints nothing whatever this is.
+		footerFill: {
+			default: {},
+			secondary: {},
+			tertiary: {},
+		},
+	},
+	compoundVariants: [
+		{ footer: "band", size: "sm", class: { footer: "-mb-3 py-3" } },
+		{ footer: "band", size: "md", class: { footer: "-mb-4 py-4" } },
+		{ footer: "band", size: "lg", class: { footer: "-mb-6 py-6" } },
+		{ footer: "band", footerFill: "default", class: { footer: "bg-card" } },
+		{ footer: "band", footerFill: "secondary", class: { footer: "bg-secondary" } },
+		{ footer: "band", footerFill: "tertiary", class: { footer: "bg-tertiary" } },
+	],
+	defaultVariants: {
+		size: "md",
+		plane: "default",
+		footer: "default",
+		footerFill: "secondary",
+	},
+});
+
+export type CardVariantProps = VariantProps<typeof cardVariants>;
+
+/**
+ * The fill a `band` footer paints: the next rung of the surface ladder from the
+ * card's own, so the band is always told apart from the card it is set into.
+ *
+ * It is the same step a surface nested in the card would take, which is the
+ * point — a band is the card's plane stepped once, not a colour of its own. A
+ * transparent card on the page has no plane, so its band takes the card fill.
+ */
+export function resolveCardFooterFill(plane: SurfacePlane | null): SurfacePlane {
+	const next = resolveSurfaceVariant({ parentPlane: plane });
+	return next === "transparent" ? "default" : next;
+}
+
+/**
+ * Splits a header's children into its text column and its trailing actions.
+ *
+ * A header is a row — the title and description stacked on the left, an action
+ * pinned to the top right — and React Native has no grid to place a child by
+ * type. So the header walks its children and lifts every action out, keeping
+ * the rest in order for the column. `Children.toArray` drops the nulls and
+ * booleans a conditional child leaves behind, so an action rendered only some
+ * of the time does not leave a hole in either list.
+ *
+ * `isAction` is passed in rather than imported so this stays free of the part
+ * it looks for, and of React Native with it.
+ */
+export function splitCardHeaderChildren(
+	children: ReactNode,
+	isAction: (node: ReactNode) => boolean
+): { text: ReactNode[]; actions: ReactNode[] } {
+	const text: ReactNode[] = [];
+	const actions: ReactNode[] = [];
+
+	for (const child of Children.toArray(children)) {
+		(isAction(child) ? actions : text).push(child);
+	}
+
+	return { actions, text };
+}

package/src/components/card/index.ts

@@ -0,0 +1,15 @@
+export { Card, type CardProps } from "./card";
+export { type CardContextValue, CardProvider, useCard, useCardContext } from "./card.context";
+export type { CardSlotProps, CardTextProps } from "./card.types";
+export {
+	CARD_FOOTER_VARIANTS,
+	CARD_PLANES,
+	CARD_SIZES,
+	type CardFooterVariant,
+	type CardPlane,
+	type CardSize,
+	type CardVariantProps,
+	cardVariants,
+	resolveCardFooterFill,
+} from "./card.variants";
+export type { CardFooterProps } from "./card-footer";