# Holo Card

A card with a procedural foil that reacts to pointer tilt and device motion.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<ComponentPreview name="holo-card" title="holo-card-demo.tsx" src="examples/holo-card-demo.tsx" previewClassName="h-auto py-8">
<HoloCardDemo />
</ComponentPreview>

Holo Card renders a surface under a procedural foil layer that shifts as the pointer moves or the device tilts. The default card layout shows a chip and a brand mark; pass a `HoloCardImage` child (or `variant="image"`) to render artwork instead. The foil is drawn with WebGL2.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add holo-card
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="holo-card" title="components/ui/holo-card.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="holo-card.tsx"
import { HoloCard, HoloCardImage } from "@/components/ui/holo-card";
```

Card mode is the default. Pass a `logo` to brand the bottom-right corner.

```tsx title="holo-card.tsx"
<HoloCard logo={<MyLogo />} />
```

Image mode keeps the artwork-first layout. Passing a `HoloCardImage` child (or `variant="image"`) switches the card into image mode.

```tsx title="holo-card.tsx"
<HoloCard variant="image">
  <HoloCardImage alt="Pikachu" src="/card.avif" />
</HoloCard>
```

`HoloCard` owns pointer tracking, tilt, device orientation, and foil rendering. `HoloCardImage` is a marker component that supplies `src` and `alt` to the parent.

## Anatomy [#anatomy]

```tsx title="holo-card.tsx"
<HoloCard logo={<MyLogo />} preset="bursts" />
```

- **HoloCard** - root container. Owns pointer tracking, tilt, orientation, and foil rendering.
- **HoloCardImage** - marker child. Switches to image mode and supplies `src` and `alt`.

## Image mode [#image-mode]

Pass a `HoloCardImage` child or set `variant="image"` to render artwork under the foil. Presets combine with both card and image modes.

### Cosmos preset, light artwork [#cosmos-preset-light-artwork]

<ComponentPreview name="holo-card" title="holo-card-cosmos-demo.tsx" src="examples/holo-card-cosmos-demo.tsx" previewClassName="h-auto py-8">
<HoloCardCosmosDemo />
</ComponentPreview>

### Bursts preset, dark artwork [#bursts-preset-dark-artwork]

<ComponentPreview name="holo-card" title="holo-card-bursts-demo.tsx" src="examples/holo-card-bursts-demo.tsx" previewClassName="h-auto py-8">
<HoloCardBurstsDemo />
</ComponentPreview>

## Presets [#presets]

| Preset | Foil shape |
| :-- | :-- |
| `bursts` | Radial bursts from the pointer position. Default. |
| `cosmos` | Layered rings and fine dust. |

## API Reference [#api-reference]

### HoloCard [#holocard]

<PropsTable />

Extends `React.ComponentProps<"div">`.

### HoloCardImage [#holocardimage]

<PropsTable rows={[{"name":"src","type":"string","required":true,"description":"Artwork URL."},{"name":"alt","type":"string","required":true,"description":"Accessible description."}]} />

Marker component. `HoloCard` reads `src` and `alt` from this child and switches to image mode.

## Accessibility [#accessibility]

- Pass a meaningful `alt` to `HoloCardImage` or the `alt` prop on `HoloCard`.
- Tilt follows the pointer on desktop and the device orientation on touch devices.
- Motion respects `prefers-reduced-motion` - tilt, springs, and orientation are disabled.
- The card is focusable only when a `backImage` is provided for flip interaction.

## Best Practices [#best-practices]

- **Use artwork that reads at a glance.** In image mode the foil adds motion; the image carries identity.
- **Provide a `logo` for card mode.** Without one, only the chip is visible in the bottom-right region.
- **Keep `intensity` between 0.6 and 0.9.** High values overwhelm text layered on top.
- **Pick `bursts` for bright palettes, `cosmos` for dark palettes.** Bursts read best on colorful art; cosmos reads best on deep backgrounds.