# PunchedTag (punched-tag)

> Card-stock luggage-style label with a punched hole and bold content, in paper, accent, or ink stock.

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

## Install

```sh
npx shadcn@latest add @jbm/punched-tag
```

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

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

## API

### `PunchedTag` (component)

A card-stock luggage tag: the two corners at the hole end cut off at 45°, the other end rounded 12px, a 14px cream punched hole ringed in ink inside a flat line-grey reinforcement washer (4px; on ink or accent stock the ring is grey too, one eyelet), and one line of 28px extra-bold content beside it that ends in an ellipsis past maxWidth. Paper's stock, shared outline (kept the same width along the cuts), and shadow. No string: tie a Hilo at the hole (VideoPrint's layout gives the point). Width follows content up to maxWidth.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | required | Tag content, usually a short name or a URL; kept on one line and cut with an ellipsis when it would pass maxWidth. |
| `tone` | `PaperTone` | `"paper"` | Stock: `paper` (card with ink text), `accent` (vermilion), or `ink`; text switches to cream on accent and ink. |
| `scale` | `number` | `1` | Size multiplier (default 1) for the tag's own geometry: hole (14 × scale px), its washer (4 × scale px), its ring (the shared outline, stroke.outline × scale, between 1px and stroke.outline), the corner cuts, radii, gap, padding, and type, so a tag on a smaller print keeps its proportions. |
| `cut` | `number` | `14` | Depth of the hole end's two 45° corner cuts in px before scale (default 14). A slim tag (VideoPrint's) passes 8. Deeper than half the tag's height, the two cuts meet in one point (edge and stock clamp alike). |
| `maxWidth` | `number \| string` | `"100%"` | Widest the tag gets, as px or a CSS length (default "100%"). Longer content stays on one line and ends in an ellipsis. In a grid or flex parent, give its track a zero minimum (minmax(0, 1fr), min-width: 0) so the one-line label cannot widen the track past the container. |
| `labelStyle` | `CSSProperties` | none | Styles merged onto the one-line label, e.g. VideoPrint's Geist Mono at 14 × scale px. The one-line rule (nowrap, hidden overflow, ellipsis) stays unless you override it. |
| `style` | `CSSProperties` | none | Inline styles merged last onto the tag's box, e.g. padding or gap. The edge sits in a transparent 3px border, so padding keeps its meaning. |

## Stage

fluid: Width follows the content (14px hole + 18px gap + text) plus 40px horizontal padding and 6px of edge (the 3px shared outline each side), capped at maxWidth (default 100% of the container). Height is one 28px line at normal line height plus 32px padding and 6px of edge; the label never wraps.

## Examples

### Ink tag

```tsx
import { PunchedTag } from "@/jbm/ui/punched-tag"

<PunchedTag tone="ink">Modelo</PunchedTag>
```

## QA

- Toggle Ink stock: the hole stays cream inside one grey eyelet (ring and washer), never a radio-button target, and the text stays legible.
- Check a long label or URL at narrow width: it stays on one line and ends in an ellipsis inside the tag, and the hole keeps its 14px circle.
- Enlarge the cut corners at 8×: the ink edge keeps the shared outline's width along each cut, meets the straight edges without a step, and no square shadow corner shows beyond the cuts.
- Compare the shadow and edge with other paper surfaces; the tag draws no string (Hilo is the connector).
- Set scale to 0.575 (a 276px VideoPrint): the hole, ring, corner cuts, radii, and type shrink together and the hole stays in proportion to the text.

## Family

Tape, clips & marks

## Docs

- [Paper and filing illustrations guide](https://jbm-ui.bns.studio/docs/design-video-components.md)

## Related

Installs:

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

Installed by:

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