# UiCard (ui-card)

> Illustrated content card with a line-art picture (hills and a vermilion sun) over two text bars.

- Entry: component
- Category: UI Bits
- Preview capabilities: none (still preview)
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/ui-card
- JSON: https://jbm-ui.bns.studio/catalog/ui-card.json
- Registry item: https://jbm-ui.bns.studio/r/ui-card.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/ui-card
```

Also installs @jbm/tokens, @jbm/paper (registry dependencies install automatically).

## Required setup

1. Add the `@jbm` registry to components.json (keep any entries already there):

   ```json
   {
     "registries": {
       "@jbm": "https://jbm-ui.bns.studio/r/{name}.json"
     }
   }
   ```

2. Map `@/*` to `./src/*` in tsconfig.json `compilerOptions.paths`, so `@/jbm/…` imports resolve to src/jbm/.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/ui-card.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/ui/ui-card.tsx` | `src/jbm/ui/ui-card.tsx` | `@/jbm/ui/ui-card` |

## API

### `UiCard` (component)

Cream paper card with an ink outline: an SVG picture slot taking half the height, then an ink title bar and a lighter subtitle bar. Padding (7% of w), radius (8% of w), and gaps (7% of h) all scale with the box. Pure React; static.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `w` | `number` | `220` | Width in stage pixels, including the 2px Paper edge; sets padding, radius, and bar widths. |
| `h` | `number` | `170` | Height in stage pixels; the picture is 50% of it and the bar thicknesses follow it. |
| `style` | `React.CSSProperties` | none | Inline styles merged over the card's column layout; use for positioning or opacity. |

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | 220 | 170 |
| Vertical (1080×1920) | 220 | 170 |

Fixed w × h box (border-box) at the defaults 220 × 170. `w` and `h` set it directly; the Paper shadow extends below the box.

## Examples

### Card at its default size

```tsx
import { UiCard } from "@/jbm/ui/ui-card"

<UiCard w={220} h={170} />
```

### Card inside a phone

```tsx
import { UiCard } from "@/jbm/ui/ui-card"
import { PhoneFrame } from "@/jbm/ui/phone-frame" // install @jbm/phone-frame separately

<PhoneFrame w={200} h={360} gap={14}>
  <UiCard w={130} h={100} />
</PhoneFrame>
```

## QA

- Inspect the picture slot: the picture width is computed as w minus padding without the 2px edges, so it may sit about 2px right of centre; confirm this is acceptable at large w.
- Try a short, wide card (h well below 0.7 × w): the picture, gaps, and two bars must still fit inside the fixed height.
- Check the single vermilion sun stays the only accent when the card sits next to other accent pieces.

## Family

Interface bits

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)
- [Paper (paper)](https://jbm-ui.bns.studio/catalog/paper.md)

Installed by:

- [Piece (piece)](https://jbm-ui.bns.studio/catalog/piece.md)

Bundled in:

- [UiBits (ui-bits)](https://jbm-ui.bns.studio/catalog/ui-bits.md)

Imported in examples:

- [PhoneFrame (phone-frame)](https://jbm-ui.bns.studio/catalog/phone-frame.md)

## More

- [llms.txt](https://jbm-ui.bns.studio/llms.txt): index of every item
- [catalog.json](https://jbm-ui.bns.studio/catalog.json): every item as JSON
- [Agent contract](https://jbm-ui.bns.studio/docs/agent-contract.md): what each field means
