# UiButton (ui-button)

> Illustrated pill button with a label bar, in ink, accent, or outlined paper tones.

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

## Install

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

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

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

## API

### `UiButton` (component)

Paper cut-out pill (radius h / 2) with a centred rounded bar standing in for the label. The bar is 42% of the width and 13% of the height (at least 6px); it is cream on ink and accent, ink on paper. Pure React with no text and no click handling: an illustration, not a control.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `w` | `number` | `220` | Width in stage pixels, including the 2px Paper edge. |
| `h` | `number` | `70` | Height in stage pixels; also sets the pill radius (h / 2) and the label bar thickness. |
| `tone` | `PaperTone` | `"ink"` | Paper stock: ink (default, filled), accent (vermilion), or paper (cream with an ink outline and ink bar). |
| `style` | `React.CSSProperties` | none | Inline styles merged over the flex centring; use for positioning, opacity, or transforms. |

## Stage

Declared in stage pixels at the documented defaults.

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

Fixed w × h box (border-box, so the 2px edge is inside) at the defaults 220 × 70. `w` and `h` set it directly; the Paper shadow extends past the box by up to about 32px below.

## Examples

### Accent button

```tsx
import { UiButton } from "@/jbm/ui/ui-button"

<UiButton w={220} h={70} tone="accent" />
```

### Outlined button in a paper row

```tsx
import { UiButton } from "@/jbm/ui/ui-button"

<div style={{ display: "flex", gap: 24 }}>
  <UiButton w={180} h={56} tone="paper" />
  <UiButton w={180} h={56} />
</div>
```

## QA

- Compare ink, accent, and paper tones on cream: the paper tone keeps its 2px ink outline and ink bar; ink and accent show a cream bar.
- Check extremes of h: at small heights the bar floors at 6px thick; at large heights the pill stays fully rounded.
- Confirm the bar stays centred when style adds padding or positioning.

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

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