@delacour/react-native-ui 0.1.0-alpha.20260925053522

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

@@ -0,0 +1,240 @@
+import { describe, expect, test } from "bun:test";
+import { TEXT_COLORS } from "../text/text.variants";
+import {
+	FIELD_LEGEND_VARIANTS,
+	FIELD_ORIENTATIONS,
+	FIELD_TEXT_PARTS,
+	type FieldTextPart,
+	fieldVariants,
+	resolveFieldInteractive,
+	resolveFieldLabelText,
+	resolveFieldTextColor,
+} from "./field.variants";
+
+/**
+ * A slot's class string, with `tv`'s empty-slot `undefined` flattened.
+ *
+ * A slot that emits nothing returns `undefined` rather than `""`, which is
+ * correct — these parts carry state only, so most are empty most of the time —
+ * but it makes a bare `not.toMatch()` throw rather than pass.
+ */
+function cls(value: string | undefined): string {
+	return value ?? "";
+}
+
+/** The gap step a class string sets — `gap-1.5` yields 1.5. */
+function gapStep(cls: string): number | undefined {
+	const value = cls.match(/\bgap-(\d+(?:\.\d+)?)\b/)?.[1];
+	return value === undefined ? undefined : Number(value);
+}
+
+/** Slots that land on a `View`, which cannot cascade colour to a `Text`. */
+const VIEW_SLOTS = ["root", "set", "group", "content", "separator"] as const;
+
+/** Slots handed to a `Text`, whose type scale comes from the preset, not from here. */
+const TEXT_SLOTS = ["label", "description", "error"] as const;
+
+describe("the root slot", () => {
+	test("lays a field out on one axis or the other, never both", () => {
+		expect(fieldVariants({ orientation: "vertical" }).root()).toContain("flex-col");
+		expect(fieldVariants({ orientation: "vertical" }).root()).not.toContain("flex-row");
+		expect(fieldVariants({ orientation: "horizontal" }).root()).toContain("flex-row");
+		expect(fieldVariants({ orientation: "horizontal" }).root()).not.toContain("flex-col");
+	});
+
+	test("centres a horizontal field on its control", () => {
+		expect(fieldVariants({ orientation: "horizontal" }).root()).toContain("items-center");
+	});
+
+	// The control belongs at the far edge, and the root pushes it there rather
+	// than the label growing into the space — a label that grew would stretch
+	// vertically the moment it moved inside a `Field.Content` column.
+	test("pushes a horizontal field's control to the far edge", () => {
+		expect(fieldVariants({ orientation: "horizontal" }).root()).toContain("justify-between");
+		expect(fieldVariants({ orientation: "vertical" }).root()).not.toContain("justify-between");
+	});
+
+	test("stacks vertically by default", () => {
+		expect(fieldVariants().root()).toBe(fieldVariants({ orientation: "vertical" }).root());
+	});
+
+	test("merges an incoming className last", () => {
+		expect(fieldVariants().root({ className: "mb-6" })).toContain("mb-6");
+		expect(fieldVariants().root({ className: "gap-8" })).not.toContain("gap-1.5");
+	});
+});
+
+// A React Native `View` does not cascade colour to a `Text` descendant, so no
+// slot worn by one may carry a colour. See AGENTS.md rule 1.
+describe("the slots that land on a View", () => {
+	test("carry no text colour", () => {
+		for (const orientation of FIELD_ORIENTATIONS) {
+			for (const isInvalid of [false, true]) {
+				for (const isDisabled of [false, true]) {
+					const slots = fieldVariants({ isDisabled, isInvalid, orientation });
+					for (const slot of VIEW_SLOTS) {
+						expect(cls(slots[slot]())).not.toMatch(/\btext-/);
+					}
+				}
+			}
+		}
+	});
+});
+
+// The whole reason four different gaps exist: a field's own parts have to read
+// as one thing, and two fields as two. Pinning the ordering rather than each
+// number keeps the test meaningful when the spacing is retuned.
+describe("the gap ladder", () => {
+	test("tightens inward, from field to field down to label and description", () => {
+		const slots = fieldVariants();
+		const content = gapStep(slots.content());
+		const root = gapStep(slots.root());
+		const set = gapStep(slots.set());
+		const group = gapStep(slots.group());
+
+		for (const gap of [content, root, set, group]) {
+			expect(gap).toBeDefined();
+		}
+		expect(content as number).toBeLessThan(root as number);
+		expect(root as number).toBeLessThan(set as number);
+		expect(set as number).toBeLessThanOrEqual(group as number);
+	});
+});
+
+describe("a disabled field", () => {
+	test("fades the label", () => {
+		expect(cls(fieldVariants({ isDisabled: true }).label())).toContain("opacity-50");
+		expect(cls(fieldVariants({ isDisabled: false }).label())).not.toContain("opacity-50");
+	});
+
+	// The control fades itself, and a description dimmed on top of an already
+	// dimmed control reads as two problems rather than one state.
+	test("leaves the description and the error alone", () => {
+		expect(cls(fieldVariants({ isDisabled: true }).description())).not.toContain("opacity-50");
+		expect(cls(fieldVariants({ isDisabled: true }).error())).not.toContain("opacity-50");
+	});
+});
+
+// The type scale belongs to the `Text` preset each part renders. A size or a
+// weight here would be a second definition of `Text.Label` that could drift
+// from it — the reason `Input` ships no label part at all. See AGENTS.md.
+describe("the slots handed to a Text", () => {
+	test("restate no type scale", () => {
+		for (const isInvalid of [false, true]) {
+			for (const isDisabled of [false, true]) {
+				const slots = fieldVariants({ isDisabled, isInvalid });
+				for (const slot of TEXT_SLOTS) {
+					expect(cls(slots[slot]())).not.toMatch(/\btext-(xs|sm|base|lg|xl|2xl|3xl)\b/);
+					expect(cls(slots[slot]())).not.toMatch(/\bfont-(normal|medium|semibold|bold)\b/);
+				}
+			}
+		}
+	});
+
+	test("carry no colour either, since that rides the preset's own axis", () => {
+		for (const isInvalid of [false, true]) {
+			const slots = fieldVariants({ isInvalid });
+			for (const slot of TEXT_SLOTS) {
+				expect(cls(slots[slot]())).not.toMatch(/\btext-\w+-?\w*\b/);
+			}
+		}
+	});
+});
+
+describe("the legend", () => {
+	test("gives its two variants different treatments", () => {
+		const seen = new Set(FIELD_LEGEND_VARIANTS.map((variant) => cls(fieldVariants({ variant }).legend())));
+		expect(seen.size).toBe(FIELD_LEGEND_VARIANTS.length);
+	});
+
+	test("merges an incoming className last", () => {
+		expect(cls(fieldVariants().legend({ className: "mb-2" }))).toContain("mb-2");
+	});
+});
+
+describe("the separator", () => {
+	test("lays its rules out in a row", () => {
+		expect(fieldVariants().separator()).toContain("flex-row");
+		expect(fieldVariants().separator()).toContain("items-center");
+	});
+
+	// Each rule takes half the leftover width so a centred label sits between
+	// them, rather than one rule being positioned behind an opaque label.
+	test("lets each rule take the space the label does not", () => {
+		expect(fieldVariants().separatorLine()).toContain("flex-1");
+	});
+});
+
+describe("resolveFieldTextColor", () => {
+	test("names a colour the Text component actually has, or nothing", () => {
+		for (const part of FIELD_TEXT_PARTS) {
+			for (const isInvalid of [false, true]) {
+				const color = resolveFieldTextColor(part, isInvalid);
+				if (color !== undefined) {
+					expect(TEXT_COLORS).toContain(color);
+				}
+			}
+		}
+	});
+
+	// The label turns with the control it names; the description stays muted so
+	// the error is the one line that changed.
+	test("reddens the label only while the field is invalid", () => {
+		expect(resolveFieldTextColor("label", true)).toBe("destructive");
+		expect(resolveFieldTextColor("label", false)).toBeUndefined();
+	});
+
+	test("leaves the description on its preset's own colour in both states", () => {
+		for (const isInvalid of [false, true]) {
+			expect(resolveFieldTextColor("description", isInvalid)).toBeUndefined();
+		}
+	});
+
+	test("keeps the error destructive even outside an invalid field", () => {
+		for (const isInvalid of [false, true]) {
+			expect(resolveFieldTextColor("error", isInvalid)).toBe("destructive");
+		}
+	});
+
+	test("covers every part it declares", () => {
+		for (const part of FIELD_TEXT_PARTS) {
+			expect(() => resolveFieldTextColor(part as FieldTextPart, true)).not.toThrow();
+		}
+	});
+});
+
+describe("resolveFieldInteractive", () => {
+	test("leaves a field of static text inert", () => {
+		// No control has offered a press, so the row stays a View. Mounting a
+		// gesture detector under every label and description in a form would
+		// announce static text as something you can activate.
+		expect(resolveFieldInteractive(null)).toBe(false);
+	});
+
+	test("hands the row to a control that offered one", () => {
+		expect(resolveFieldInteractive(() => undefined)).toBe(true);
+	});
+});
+
+describe("resolveFieldLabelText", () => {
+	test("hands a string label through, trimmed", () => {
+		expect(resolveFieldLabelText("Volume")).toBe("Volume");
+		expect(resolveFieldLabelText("  Volume\n")).toBe("Volume");
+	});
+
+	test("reads a number the way a screen reader would", () => {
+		expect(resolveFieldLabelText(42)).toBe("42");
+	});
+
+	// A label made of elements has no text this side of a render, and an empty
+	// string is not a name — both leave the control to name itself.
+	test("offers nothing for an element, an empty string, or no children at all", () => {
+		expect(resolveFieldLabelText("")).toBeNull();
+		expect(resolveFieldLabelText("   ")).toBeNull();
+		expect(resolveFieldLabelText(undefined)).toBeNull();
+		expect(resolveFieldLabelText(null)).toBeNull();
+		expect(resolveFieldLabelText(false)).toBeNull();
+		expect(resolveFieldLabelText({ type: "Text", props: {} })).toBeNull();
+		expect(resolveFieldLabelText(["a", "b"])).toBeNull();
+	});
+});

package/src/components/field/field.variants.ts

@@ -0,0 +1,156 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import type { TextColor } from "../text/text.variants";
+
+export const FIELD_ORIENTATIONS = ["vertical", "horizontal"] as const;
+
+export const FIELD_LEGEND_VARIANTS = ["legend", "label"] as const;
+
+/** The parts that render a `Text` and therefore need a colour rather than a class. */
+export const FIELD_TEXT_PARTS = ["label", "description", "error"] as const;
+
+export type FieldOrientation = (typeof FIELD_ORIENTATIONS)[number];
+export type FieldLegendVariant = (typeof FIELD_LEGEND_VARIANTS)[number];
+export type FieldTextPart = (typeof FIELD_TEXT_PARTS)[number];
+
+/**
+ * Layout for a form field and the structures that hold one.
+ *
+ * One slotted `tv()` rather than a call per part, so the spacing ladder is
+ * declared in a single place. That ladder is the component: `content` groups a
+ * label with its description, `root` groups a field's parts, `set` groups a
+ * legend with its fields, and `group` separates one field from the next. Each
+ * step is looser than the one inside it, which is what makes a field read as one
+ * thing and two fields as two — `field.variants.test.ts` pins the ordering
+ * rather than the numbers, so the spacing can be retuned without the test
+ * becoming a transcript of it.
+ *
+ * **No slot here carries a type scale or a colour.** The text parts render the
+ * `Text` presets — `Text.Label`, `Text.Caption` — and pass a colour through
+ * {@link resolveFieldTextColor}, so the scale lives in exactly one place. A
+ * `text-sm font-medium` written here would be a second definition of
+ * `Text.Label` that could drift from it, which is the reason `Input` ships no
+ * label part of its own. The slots hold state and layout only.
+ *
+ * The `View` slots hold no `text-*` at all: a React Native `View` does not
+ * cascade colour to a `Text` descendant. See AGENTS.md rule 1.
+ *
+ * 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 fieldVariants = tv({
+	slots: {
+		root: "w-full gap-1.5",
+		/** A legend, its description and the fields under them. */
+		set: "w-full gap-4",
+		/** Field to field — the loosest step, so two fields never read as one. */
+		group: "w-full gap-5",
+		/** A label and its description, as one block beside a control. */
+		content: "min-w-0 flex-1 gap-0.5",
+		label: "",
+		description: "",
+		error: "",
+		legend: "",
+		/** The row a separator's rules and its optional label share. */
+		separator: "w-full flex-row items-center gap-3",
+		/** Each rule takes the width the label does not. */
+		separatorLine: "flex-1",
+	},
+	variants: {
+		orientation: {
+			vertical: { root: "flex-col" },
+			// `justify-between` is what pushes the control to the far edge, and it
+			// is the root's job rather than the label's. The web kit grows the label
+			// instead — `*:data-[slot=field-label]:flex-auto` — which needs a child
+			// selector uniwind does not have, and would stretch the label vertically
+			// once it sat inside a `Field.Content` column rather than beside it.
+			horizontal: { root: "flex-row items-center justify-between" },
+		},
+		variant: {
+			legend: { legend: "font-medium" },
+			label: { legend: "" },
+		},
+		// 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`. See the note in
+		// button.variants.ts.
+		isInvalid: { true: {}, false: {} },
+		// Only the label fades. The control dims itself, and a description
+		// dimmed on top of an already dimmed control reads as two problems
+		// rather than one state.
+		isDisabled: { true: { label: "opacity-50" }, false: {} },
+	},
+	defaultVariants: {
+		orientation: "vertical",
+		variant: "legend",
+		isInvalid: false,
+		isDisabled: false,
+	},
+});
+
+/**
+ * The `Text` colour a text part takes, given the field's state.
+ *
+ * Returning `undefined` is meaningful rather than lazy: `Text`'s `color` axis
+ * emits nothing when it is not named, so the part falls through to its preset's
+ * own colour — `text-foreground` for a label, `text-muted-foreground` for a
+ * description. That is what lets a part say "leave it alone" without knowing
+ * which token its preset chose.
+ *
+ * The label turns with the control it names, so the pair reads as one state. The
+ * description stays muted in both, so the error is the one line that appeared.
+ * The error is destructive even outside an invalid field, because an error message is
+ * never the calm case.
+ *
+ * Pure, so the whole matrix is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveFieldTextColor(part: FieldTextPart, isInvalid: boolean): TextColor | undefined {
+	switch (part) {
+		case "label":
+			return isInvalid ? "destructive" : undefined;
+		case "error":
+			return "destructive";
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Whether the field's row should render as a `Pressable` rather than a `View`.
+ *
+ * Only once a control inside has offered a press. A field is layout until then,
+ * and mounting a `GestureDetector` regardless would put one under every label
+ * and description in a form — the same thing `Badge` refuses to do for a list of
+ * fifty tags, and for the same reason: assistive technology would announce a row
+ * of static text as something you can activate.
+ *
+ * A type predicate rather than a plain boolean, so the branch that renders the
+ * `Pressable` gets a non-null `onPress` out of the same check that decided it.
+ *
+ * Pure, so the decision is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveFieldInteractive(press: (() => void) | null): press is () => void {
+	return press !== null;
+}
+
+/**
+ * The text a `Field.Label` can lend to the control beside it as its accessible
+ * name, or `null` when it has none to lend.
+ *
+ * Only a bare string or number qualifies. A label built from elements has no
+ * text this side of a render, and guessing at one would name a control after
+ * the wrong thing — an icon's key, say. Whitespace is trimmed and an empty
+ * string is an absence, because a screen reader handed `""` reads nothing at
+ * all, which is worse than reading the value alone.
+ *
+ * React Native has no `<label for>`; this is the association, done by hand
+ * through the field's context. Pure, so `bun test` reaches it. See AGENTS.md.
+ */
+export function resolveFieldLabelText(children: unknown): string | null {
+	if (typeof children === "number") return String(children);
+	if (typeof children !== "string") return null;
+	const text = children.trim();
+	return text === "" ? null : text;
+}
+
+export type FieldVariantProps = VariantProps<typeof fieldVariants>;

package/src/components/field/index.ts

@@ -0,0 +1,22 @@
+export { Field, type FieldProps } from "./field";
+export { type FieldContextValue, FieldProvider, useField, useFieldContext } from "./field.context";
+export type { FieldTextProps } from "./field.types";
+export {
+	FIELD_LEGEND_VARIANTS,
+	FIELD_ORIENTATIONS,
+	FIELD_TEXT_PARTS,
+	type FieldLegendVariant,
+	type FieldOrientation,
+	type FieldTextPart,
+	type FieldVariantProps,
+	fieldVariants,
+	resolveFieldInteractive,
+	resolveFieldLabelText,
+	resolveFieldTextColor,
+} from "./field.variants";
+export type { FieldContentProps } from "./field-content";
+export type { FieldErrorProps } from "./field-error";
+export type { FieldGroupProps } from "./field-group";
+export type { FieldLegendProps } from "./field-legend";
+export type { FieldSeparatorProps } from "./field-separator";
+export type { FieldSetProps } from "./field-set";

package/src/components/icon/AGENTS.md

@@ -0,0 +1,104 @@
+# Icon
+
+Renders a Central Icon at a theme-aware size and colour. Pattern A in
+[The three component patterns](../../../AGENTS.md#the-three-component-patterns) —
+a styled wrapper with no state and no compound surface, which also reads
+`IconDefaultsProvider` so a parent can set size and colour for its whole subtree
+instead of every call site repeating them.
+
+`import { Icon } from "@delacour/react-native-ui/icon";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/icon` |
+| `icon.tsx` | `Icon`, the `IconGlyph` proxy and the one `withUniwind` wrapper (see rule 7) — internal below `Icon` |
+| `icon.context.tsx` | `IconDefaults`, `IconDefaultsProvider`, `useIconDefaults()` |
+| `icon.variants.ts` | Pure `tv()` + the size-class ladder, no RN imports |
+| `icon.variants.test.ts` | |
+
+## Design
+
+- **Props**: `icon` — required, a Central Icon component; `size` — a named step
+  or an edge length in points; `color` — a theme colour token, a CSS variable
+  name or a literal; `className` — a `size-*` utility. It extends `SvgProps`
+  with `color`, `width` and `height` removed, because those three are the axes
+  `Icon` owns: `color` is resolved through the theme, and width and height
+  arrive as the glyph's `size` prop rather than as props of their own.
+- **Sizes**: `xs`, `sm`, `md`, `lg`, `xl`, `2xl` — 14/16/18/20/24/32pt, held as
+  `size-icon-*` token classes rather than numbers, plus a numeric escape hatch.
+  With no `size`, no `className` and nothing to inherit the fallback is
+  `size-icon-lg`, 20pt, on the `foreground` token.
+- **Precedence is a five-source ladder** and it is shared with `Spinner`, so it
+  is documented once in the package doc — see
+  [Sizing](../../../AGENTS.md#sizing) for the table and for why a numeric size
+  can never become a class. `resolveIconSizeClass` builds the first four sources
+  as one `cn()` chain, so the last `size-*` wins; a numeric `size` bypasses the
+  chain entirely.
+- **Overriding through `className` uses `size-*`, not `w-*` with `h-*`.**
+  tailwind-merge conflicts `size` into `w`/`h` but not the reverse, so a trailing
+  `w-6` will not clear a leading `size-5`.
+- **Size and colour are inherited, not passed.** `IconDefaultsProvider` supplies
+  the class and the token that an unstyled `Icon` in its subtree adopts, and
+  `useIconDefaults()` reads the nearest one — `null` outside a provider. This is
+  what lets an icon be *composed into* a component rather than passed as a prop:
+  `<Button><Icon icon={IconPlus} /><Button.Label>Add</Button.Label></Button>`
+  sizes and tints the icon for the button's variant, with no `startIcon` prop and
+  no colour repeated at the call site. An explicit `size` or `color` on the icon
+  still wins.
+- **The components that publish it** are
+  [Button](../button/AGENTS.md), `Badge`, `Switch.Content`, `Switch.Thumb`,
+  `Tabs.Trigger`, `Accordion.Trigger`, `Accordion.Indicator`,
+  `Input.Group`'s decorators, `ListGroup.ItemPrefix`, `Screen.Navbar.BackButton`
+  and [Spinner](../spinner/AGENTS.md) — each carrying its own step on the shared
+  scale and its own variant's foreground token.
+- **An icon's size is a class; an icon's colour is a token.** The asymmetry is
+  deliberate — a colour class cannot express a literal like `#EC4899` or reach an
+  SVG paint prop, so `color` is resolved through the active theme by
+  `useThemeColor` instead. See [Theming](../../../AGENTS.md#theming).
+- **`iconVariants` has no `defaultVariants`, on purpose.** The fall-through *is*
+  the feature: a default would emit from inside that same `tv()` call, ahead of
+  an inherited class in the merge, and the fallback would then beat the enclosing
+  component. An unnamed axis must reach the inherited provider rather than be
+  answered locally, so `resolveIconSizeClass` orders the sources instead. The
+  variant test pins it — without a size, `iconVariants()` emits no `size-*` at
+  all.
+- **The `withUniwind` wrapper is forced, not stylistic.** A className cannot size
+  a Central Icon through a style: `CentralIconBase` spreads its props onto
+  `<Svg>` *before* setting its own `width`/`height`, and `react-native-svg`'s
+  `Svg.render()` then merges `{...style, ...props}` and pushes the
+  width/height-derived styles onto the root **last**, so a `size-4` that resolved
+  to `style.width` is overridden every single time. `icon.tsx` runs the class
+  through `withUniwind` in manual mode to recover the width and hands that number
+  to the glyph's `size` prop.
+- **The wrapper goes on a proxy that takes the glyph as data.** `IconGlyph`
+  renders whatever component it is handed, so a *single* `withUniwind` covers the
+  whole two-thousand-icon set instead of one per glyph — still one component
+  wrapped once, in one file. It also drops the `className` that sized it, because
+  `withManualUniwind` spreads the original props straight through and
+  `CentralIconBase` would forward a stray `className` onto the native SVG view,
+  where nothing interprets it.
+- **`withUniwind` is called at module scope.** In render it would mint a new
+  component type every frame and remount the icon.
+- **This is the single sanctioned carve-out from rule 7, and it is already
+  spent.** Do not wrap a Central Icon directly, do not wrap the proxy anywhere
+  else, and do not add a second wrapper for `Svg`.
+- **`Icon` and `Spinner` share one scale.** `SPINNER_SIZES` *is* `ICON_SIZES`, so
+  `size="md"` is the same edge length in both and one can stand in for the other
+  with nothing moving — which is what makes a button's loading swap free. See
+  [Spinner](../spinner/AGENTS.md).
+- **Central Icons only**, via `@delacour/react-native-ui/icons/central` — never Lucide,
+  Hugeicons, or anything else. That is rule 5.
+- **`icon.variants.ts` is free of React Native imports** so the whole ladder is
+  reachable from `bun test` — `resolveIconSizeClass`, `isIconSize` and
+  `iconVariants` are all pure. See [Testing](../../../AGENTS.md#testing).
+
+## Known gaps
+
+- **`Icon` is the only component with no playground route.** Step 5 of
+  [Adding a component](../../../AGENTS.md#adding-a-component) requires
+  `apps/playground/src/app/(components)/{name}.tsx` plus a row on the index, and
+  exempts only a component with nothing to render — `DelacourProvider`. `Icon`
+  renders, so it does not qualify for that exemption; it is verified today only
+  indirectly, through the glyphs on the other routes.

package/src/components/icon/icon.context.tsx

@@ -0,0 +1,29 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+
+export type IconDefaults = {
+	/** Classes an unstyled `Icon` in this subtree adopts, e.g. `size-4.5`. */
+	className: string;
+	/** Theme colour token, e.g. `primary-foreground`. */
+	color: string;
+};
+
+const IconDefaultsContext = createContext<IconDefaults | null>(null);
+
+/**
+ * Supplies the size and colour that unstyled `Icon`s in this subtree adopt.
+ *
+ * This is what lets an icon be *composed into* a component rather than passed
+ * as a prop: `<Button><Icon icon={IconPlus} /><Button.Label>Add</Button.Label></Button>`
+ * sizes and tints the icon for the button's variant, with no `startIcon` prop
+ * and no colour repeated at the call site. An explicit `size` or `color` on the
+ * icon still wins.
+ */
+export function IconDefaultsProvider({ value, children }: { value: IconDefaults; children: ReactNode }): ReactElement {
+	return <IconDefaultsContext value={value}>{children}</IconDefaultsContext>;
+}
+IconDefaultsProvider.displayName = "DelacourUI.Icon.DefaultsProvider";
+
+/** Icon defaults from the nearest provider, or null outside one. */
+export function useIconDefaults(): IconDefaults | null {
+	return use(IconDefaultsContext);
+}

package/src/components/icon/icon.tsx

@@ -0,0 +1,92 @@
+import type { ComponentType, ReactElement } from "react";
+import type { SvgProps } from "react-native-svg";
+import { withUniwind } from "uniwind";
+import { useThemeColor } from "../../hooks/use-theme-color";
+import { useIconDefaults } from "./icon.context";
+import { ICON_FALLBACK_COLOR, type IconSize, isIconSize, resolveIconSizeClass } from "./icon.variants";
+
+export type IconComponent = ComponentType<SvgProps & { size?: number | string }>;
+
+export type IconProps = Omit<SvgProps, "color" | "width" | "height"> & {
+	/** An icon component from `@delacour/react-native-ui/icons/central`. */
+	icon: IconComponent;
+	/** A named size, or an edge length in points. A number beats `className`. */
+	size?: IconSize | number;
+	/**
+	 * A theme colour token (`foreground`, `muted-foreground`, …) or a CSS
+	 * variable name. Defaults to the enclosing component's icon colour.
+	 */
+	color?: string;
+	/** A `size-*` utility. Beats a named `size`, loses to a numeric one. */
+	className?: string;
+};
+
+type IconGlyphProps = Omit<SvgProps, "color" | "width" | "height"> & {
+	glyph: IconComponent;
+	size?: number | string;
+	color?: string;
+	className?: string;
+};
+
+/**
+ * Renders the glyph and drops the className that sized it.
+ *
+ * This one indirection is what keeps the whole Central Icons set to a *single*
+ * `withUniwind` wrapper: the wrapper goes on this component, which takes the
+ * glyph as data, rather than on each of the two thousand icon components.
+ * AGENTS.md rule 7 caps a component at one wrapper in one file — this is it.
+ *
+ * The className must not reach the glyph. `withManualUniwind` spreads the
+ * original props straight through, and `CentralIconBase` would forward a stray
+ * `className` onto the native SVG view, where nothing interprets it.
+ */
+function IconGlyph({ glyph: Glyph, className: _sizedBy, ...props }: IconGlyphProps): ReactElement {
+	return <Glyph {...props} />;
+}
+IconGlyph.displayName = "DelacourUI.Icon.Glyph";
+
+/**
+ * Turns a `size-*` class into the glyph's `size` **prop**.
+ *
+ * A className cannot size an SVG through a style: `CentralIconBase` spreads its
+ * props onto `<Svg>` before its own `width`/`height`, and `Svg.render` pushes
+ * the width/height-derived styles on last, beating anything a className set.
+ *
+ * `withManualUniwind` reads `props.className`, compiles it, and writes
+ * `styles.width` to `size` — but skips the mapping entirely when `size` is
+ * already defined. That skip *is* the precedence rule: a numeric `size` from the
+ * caller wins and the class is ignored.
+ *
+ * Created once at module scope. Calling `withUniwind` inside a render would mint
+ * a new component type every frame and remount the icon.
+ */
+const StyledIconGlyph = withUniwind(IconGlyph, {
+	size: { fromClassName: "className", styleProperty: "width" },
+});
+
+/**
+ * Renders a Central Icon at a theme-aware size and colour.
+ *
+ * An icon's size is a class and an icon's colour is a token — a class cannot
+ * express a literal like `#EC4899` or reach an SVG paint prop, so colour is
+ * resolved through the active theme instead. See AGENTS.md.
+ *
+ * Both fall back to the nearest {@link IconDefaultsProvider}, so an icon
+ * composed into a Button matches that button's size and variant without being
+ * told to. An explicit `size` or `color` still wins.
+ */
+export function Icon({ icon, size, color, className, ...props }: IconProps): ReactElement {
+	const defaults = useIconDefaults();
+	const resolvedColor = useThemeColor(color ?? defaults?.color ?? ICON_FALLBACK_COLOR);
+
+	return (
+		<StyledIconGlyph
+			className={resolveIconSizeClass({ className, inherited: defaults?.className, size })}
+			color={resolvedColor}
+			glyph={icon}
+			size={isIconSize(size) ? undefined : size}
+			{...props}
+		/>
+	);
+}
+Icon.displayName = "DelacourUI.Icon";