# PhoneFrame (phone-frame)

> Phone silhouette with a thick ink edge and speaker slot that stacks your content at the bottom of its screen.

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

## Install

```sh
npx shadcn@latest add @jbm/phone-frame
```

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/phone-frame.json, files[].content).

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

## API

### `PhoneFrame` (component)

Card-stock phone with an ink edge (1.6% of w, at least 5px), corner radius 13% of w, the paper shadow, and a speaker slot near the top. Children lay out as a centred column pushed to the bottom of the screen (justify flex-end). Content is not clipped or scaled to fit.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `w` | `number` | `420` | Width in stage pixels, including the edge; sets edge thickness, radius, padding (10% of w, plus 8% extra on top), and the speaker slot. |
| `h` | `number` | `780` | Height in stage pixels, including the edge. |
| `rotate` | `number` | `0` | Tilt in degrees; applied as a CSS rotate, so the layout box stays w × h. |
| `children` | `React.ReactNode` | none | Screen content, stacked as a column from the bottom up. |
| `style` | `React.CSSProperties` | none | Inline styles merged last; can override padding, alignment, or transform. |
| `gap` | `number` | `26` | Space between children in stage pixels. |

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | 420 | 780 |
| Vertical (1080×1920) | 420 | 780 |

Fixed w × h box (border-box) at the defaults 420 × 780. `w` and `h` set it directly; `rotate` tilts it visually without changing the layout box, and the shadow extends below.

## Examples

### Phone holding interface pieces

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

<PhoneFrame w={200} h={360} gap={14} rotate={-2}>
  <UiCard w={130} h={100} />
  <UiButton w={130} h={40} />
</PhoneFrame>
```

## QA

- Fill the screen with children taller than the inner area: they overflow the top edge (nothing clips), so size content to h minus the padding.
- Check small w: the edge floors at 5px and the speaker slot at 5px tall.
- Rotate by a few degrees and confirm corners and shadow stay inside the composition's safe area.

## 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)

Bundled in:

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

Imported in examples:

- [UiCard (ui-card)](https://jbm-ui.bns.studio/catalog/ui-card.md)
- [UiButton (ui-button)](https://jbm-ui.bns.studio/catalog/ui-button.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
