# Piece (piece)

> Picks the button, input, or card illustration by kind and sizes it from one width.

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

## Install

```sh
npx shadcn@latest add @jbm/piece
```

Also installs @jbm/paper, @jbm/ui-button, @jbm/ui-input, @jbm/ui-card (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/piece.json, files[].content).

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

## API

### `Piece` (component)

Renders UiButton, UiInput, or UiCard for `kind` at width `w`; height follows each piece's proportion (button and input 0.32 × w, card 0.78 × w). Lets a list of `{ kind }` entries render interface pieces without branching.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `PieceKind` | required | Which piece to draw: button, input, or card. |
| `w` | `number` | required | Width in stage pixels; height is derived from it per kind. |
| `tone` | `PaperTone` | none | Button tone only (ink by default, accent, or paper); ignored by input and card. |
| `cursorOn` | `boolean` | none | Input only: shows or hides the text cursor (UiInput default: shown); ignored by button and card. |
| `style` | `React.CSSProperties` | none | Inline styles forwarded to the chosen piece. |

### `PieceKind` (type)

The piece names: "button" | "input" | "card".

## Stage

Declared in stage pixels at the documented defaults.

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

No defaults: `w` is required. At w = 220 a button or input is 220 × 70 (round(0.32 × w)); a card is 220 × 172 (round(0.78 × w)).

## Examples

### One button

```tsx
import { Piece } from "@/jbm/ui/piece"

<Piece kind="button" w={220} />
```

### A row of every kind

```tsx
import { Piece, type PieceKind } from "@/jbm/ui/piece"

const kinds: PieceKind[] = ["button", "input", "card"]
<div style={{ display: "flex", gap: 30, alignItems: "center" }}>
  {kinds.map((kind) => <Piece key={kind} kind={kind} w={180} tone="accent" cursorOn={false} />)}
</div>
```

## QA

- Render all three kinds at the same w and check their heights (0.32, 0.32, 0.78 × w) and baseline alignment in a row.
- Pass tone and cursorOn to each kind: tone changes only the button and cursorOn only the input.

## Family

Interface bits

## Related

Installs:

- [Paper (paper)](https://jbm-ui.bns.studio/catalog/paper.md)
- [UiButton (ui-button)](https://jbm-ui.bns.studio/catalog/ui-button.md)
- [UiInput (ui-input)](https://jbm-ui.bns.studio/catalog/ui-input.md)
- [UiCard (ui-card)](https://jbm-ui.bns.studio/catalog/ui-card.md)

Bundled in:

- [UiBits (ui-bits)](https://jbm-ui.bns.studio/catalog/ui-bits.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
