# Integrate `Aperture` from Motion Garden

You are helping me add the **Aperture** component to an existing project.
Everything you need is below — full source, dependencies, props and the
behavioural contract. Read it all before writing anything.

- **Component:** Aperture
- **Category:** Micro-interactions
- **Summary:** A camera iris. Blades pivot on a ring of pins and one shared angle drives the whole mechanism: wide open at 64% of the housing, past the centre and light-tight at zero, cutting the scalloped polygon a real iris makes on the way through.
- **Reference:** https://motion-garden.netlify.app/components/aperture
- **Full catalog (for you, the agent):** https://motion-garden.netlify.app/llms.txt

## Stack this source assumes

- React 19 with the Next.js App Router (never the `pages/` directory)
- TypeScript, strict
- Tailwind CSS v4, CSS-first config (utilities are inline; no `tailwind.config` needed)

If my project differs, adapt the integration — but do not rewrite the animation math to suit a different stack. Ask me first.

## Dependencies

```bash
bun add motion clsx tailwind-merge
```

## Files to create

2 files — all of them are required. Paths are as shipped; the component may live anywhere in my project, but keep every peer file at the exact path shown so the import aliases resolve.

### 1. `components/registry/aperture/aperture.tsx`

```tsx
"use client";

import { useEffect, useId, useRef, type ReactNode } from "react";
import { animate, motion, useMotionValue, useTransform } from "motion/react";
import { cn } from "@/lib/utils";

export interface ApertureProps {
	children?: ReactNode;
	bladeCount?: number;
	openness?: number;
	duration?: number;
	detent?: number;
	bladeCurvature?: number;
	edgeHighlight?: number;
	housingInset?: number;
	autoOpen?: boolean;
	bladeColor?: string;
	edgeColor?: string;
	reducedMotion?: boolean;
	className?: string;
}

const BASE_RHO = 160;

const OPEN_MIN = -5;
const OPEN_MAX = 64;

const LIGHT = -55;

const FLOOR_OUT = 300;

const phiFor = (openness: number) =>
	Math.PI * (1 - Math.min(1, Math.max(0, openness)));

const dist = (p: number, pivot: number, arm: number) =>
	Math.sqrt(pivot * pivot + arm * arm + 2 * pivot * arm * Math.cos(p));

export default function Aperture({
	children,
	bladeCount = 8,
	openness = 0.62,
	duration = 900,
	detent = 0.35,
	bladeCurvature = 1,
	edgeHighlight = 0.6,
	housingInset = 6,
	autoOpen = true,
	bladeColor = "#26232c",
	edgeColor = "#000000",
	reducedMotion = false,
	className,
}: ApertureProps) {
	const phi = useMotionValue(phiFor(openness));

	const rho = BASE_RHO * bladeCurvature;
	const arm = (OPEN_MAX - OPEN_MIN) / 2;
	const pivot = rho + (OPEN_MAX + OPEN_MIN) / 2;

	const count = Math.max(3, Math.round(bladeCount));
	const blades = Array.from({ length: count }, (_, i) => i);
	const angle = (i: number) => (i * 360) / count;

	const uid = useId().replace(/[^a-zA-Z0-9_-]/g, "");

	const cx = useTransform(phi, (p) => pivot + arm * Math.cos(p));
	const cy = useTransform(phi, (p) => arm * Math.sin(p));

	const live = useRef({ duration, detent, openness });
	live.current = { duration, detent, openness };

	useEffect(() => {
		const ease = () =>
			[0.34, 1 + live.current.detent, 0.64, 1] as [
				number,
				number,
				number,
				number,
			];

		if (reducedMotion || !autoOpen) {
			animate(
				phi,
				phiFor(live.current.openness),
				reducedMotion
					? { duration: 0 }
					: { duration: live.current.duration / 1000, ease: ease() },
			);
			return;
		}

		let alive = true;
		let timer: ReturnType<typeof setTimeout> | null = null;

		const leg = (open: boolean) => {
			void animate(phi, phiFor(open ? 0.95 : 0.08), {
				duration: live.current.duration / 1000,
				ease: ease(),
			}).then(() => {
				if (!alive) return;
				timer = setTimeout(() => {
					if (alive) leg(!open);
				}, 720);
			});
		};
		leg(true);

		return () => {
			alive = false;
			if (timer !== null) clearTimeout(timer);
		};
	}, [autoOpen, reducedMotion, openness, duration, phi]);

	const vertexR = (p: number) => {
		const d = dist(p, pivot, arm);
		const s = Math.sin(Math.PI / count);
		const under = rho * rho - d * d * s * s;
		const r =
			under > 0 ? d * Math.cos(Math.PI / count) - Math.sqrt(under) : d - rho;
		return Math.max(0, r);
	};

	const floorR = useTransform(phi, (p) => (vertexR(p) + FLOOR_OUT) / 2);
	const floorW = useTransform(phi, (p) => FLOOR_OUT - vertexR(p));

	const lightRad = (LIGHT * Math.PI) / 180;
	const lx = Math.cos(lightRad) * 100;
	const ly = Math.sin(lightRad) * 100;

	const litAt = (i: number) =>
		0.5 + 0.5 * Math.cos(((angle(i) - LIGHT) * Math.PI) / 180);

	return (
		<div
			className={cn(
				"relative aspect-square overflow-hidden rounded-full",
				className,
			)}
			style={{ backgroundColor: bladeColor }}
		>
			<div className="absolute inset-0">{children}</div>

			<svg
				viewBox="-100 -100 200 200"
				className="absolute inset-0 h-full w-full"
				aria-hidden
			>
				<defs>
					<clipPath id={`${uid}-housing`} clipPathUnits="userSpaceOnUse">
						<circle cx="0" cy="0" r="100" />
					</clipPath>

					<linearGradient
						id={`${uid}-sheen`}
						gradientUnits="userSpaceOnUse"
						x1={lx}
						y1={ly}
						x2={-lx}
						y2={-ly}
					>
						<stop offset="0" stopColor="#ffffff" stopOpacity="0.08" />
						<stop offset="0.5" stopColor="#ffffff" stopOpacity="0" />
						<stop offset="1" stopColor="#000000" stopOpacity="0.24" />
					</linearGradient>

					{blades.map((i) => (
						<mask
							key={i}
							id={`${uid}-cut-${i}`}
							maskUnits="userSpaceOnUse"
							x="-100"
							y="-100"
							width="200"
							height="200"
						>
							<rect
								x="-100"
								y="-100"
								width="200"
								height="200"
								fill="#ffffff"
							/>
							<g transform={`rotate(${angle((i + 1) % count)})`}>
								<motion.circle cx={cx} cy={cy} r={rho} fill="#000000" />
							</g>
						</mask>
					))}
				</defs>

				<g clipPath={`url(#${uid}-housing)`}>
					<motion.circle
						cx="0"
						cy="0"
						r={floorR}
						fill="none"
						stroke={bladeColor}
						strokeWidth={floorW}
					/>

					{blades.map((i) => (
						<g key={i} transform={`rotate(${angle(i)})`}>
							<motion.circle cx={cx} cy={cy} r={rho} fill={bladeColor} />
						</g>
					))}

					<rect
						x="-100"
						y="-100"
						width="200"
						height="200"
						fill={`url(#${uid}-sheen)`}
					/>

					{blades.map((i) => (
						<g key={i} mask={`url(#${uid}-cut-${i})`}>
							<g transform={`rotate(${angle(i)})`}>

								<motion.circle
									cx={cx}
									cy={cy}
									r={rho}
									fill="none"
									stroke={edgeColor}
									strokeOpacity={edgeHighlight * (0.62 + 0.38 * litAt(i))}
									strokeWidth="1"
								/>
							</g>
						</g>
					))}
				</g>

				<circle
					cx="0"
					cy="0"
					r={100 - housingInset / 2}
					fill="none"
					stroke={bladeColor}
					strokeWidth={housingInset}
				/>
				<circle
					cx="0"
					cy="0"
					r={100 - housingInset}
					fill="none"
					stroke={edgeColor}
					strokeOpacity={edgeHighlight * 0.5}
					strokeWidth="0.7"
				/>
			</svg>
		</div>
	);
}
```

### 2. `lib/utils.ts` — peer util, required

```tsx
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}
```


## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bladeCount` | `number` | `8` | How many leaves in the mechanism. Low counts give the hard hexagonal bokeh of a cheap lens; past nine the opening is indistinguishable from a circle, which is exactly what expensive glass is sold on. Range 3–12. |
| `openness` | `number` | `0.62` | Where the blades rest, 0 shut to 1 wide. At 0 they cross past the centre rather than merely meeting it — an iris that only just touches leaks light. Range 0–1. Ignored while `autoOpen` is `true`. |
| `duration` | `number` | `900` | Time for one full open or close. Range 150–2500 ms. |
| `detent` | `number` | `0.35` | Overshoot as the mechanism seats. 0 arrives dead, which reads as software; a little bounce reads as a part with mass hitting its stop. Range 0–1. |
| `bladeCurvature` | `number` | `1` | Curvature of each blade's inner edge. The mechanism is derived from the opening range, so this bends the leaf without touching the travel: flatter blades cut a rounder, more regular polygon, tighter ones pull the scallop corners out into a star. Range 0.6–1.4 ×. |
| `edgeHighlight` | `number` | `0.6` | Strength of the seam along each leaf's inner edge, and of the bezel. Each seam is cut by the leaf that lies over it — named rather than left to the drawing order, because a leaf stack is a ring and painter's order is a line. That is what puts exactly one line at every corner of the opening, wide open and shut alike. Range 0–1. |
| `housingInset` | `number` | `6` | Width of the machined ring inside the rim. It is drawn over the blades, so the housing reads as the part they are seated in rather than one more leaf. Range 0–24. |
| `autoOpen` | `boolean` | `true` | Open and shut on a loop. Turning it off hands the mechanism to the openness slider. |
| `bladeColor` | `string (hex)` | `"#26232c"` | Body of the blades, the housing, and the barrel floor behind them. Its own material rather than a themed surface — a light theme must not put a white ring around a lens. |
| `edgeColor` | `string (hex)` | `"#000000"` | Amethyst on the blade seams and the bezel. |

## Usage

```tsx
import Aperture from "@/components/registry/aperture/aperture";

<Aperture
  bladeCount={8}
  openness={0.62}
  duration={900}
  detent={0.35}
  bladeCurvature={1}
  edgeHighlight={0.6}
  housingInset={6}
  autoOpen={true}
  bladeColor="#26232c"
  edgeColor="#000000"
/>
```

The import path matches the file path above; change it if you move the component. Every value shown is the documented default — pass only what you actually want to change. The snippet lists the tunable props only: if the component's props type in the source requires others (content, handlers, data), pass those too.

## Integration rules

- Keep the `"use client"` directive. This is a client component and will not render as a Server Component.
- It fills its parent. Give the wrapper an explicit height (or a definite grid area) — against a height-auto parent it collapses to nothing.
- It takes a `reducedMotion` prop and quiesces when true. Wire it to a `prefers-reduced-motion` listener rather than hardcoding `false`.
- `lib/utils.ts` is required, not optional. It exports the `cn` helper the component imports from `@/lib/utils` — keep it at that path, or rewrite every `cn` import to wherever you already keep yours. If your project is shadcn-based you almost certainly have this file already; keep yours and drop mine.

## Your task

1. Tell me where in my project this should live and why.
2. Create the files above verbatim.
3. Wire the component into the place I point you at, with sensible props for that context.
4. Flag anything in my setup that conflicts with the stack assumptions above.

Do not restyle the component or alter the animation math unless I ask.
